comment-parser.node.txt

                  
   COMMENT-PARSER  
                  



ALTERNATIVES ==>                  #  - comment-parser (preferred): streaming mode, more high-profile
                                  #  - jest-docblock: only top of file, can strip
                                  #  - parse-comments

VERSION ==>                       #1.4.1

COMMENT-PARSER(STR[, OPTS])       #Parse JSDoc-like comments:
 ->BLOCK_ARR                      #  /**
                                  #   * DESCRIPTION
                                  #   * @TAG [{TYPE}] [[NAME[=VAL]]] DESCRIPTION
                                  #   * ...
                                  #   */
                                  #Comments starting with /*** or /* are ignored
                                  #OPTS:
                                  #  - startLine NUM (def: 1)
                                  #  - spacing: how to concatenate whitespaces, among 'compact' (def) or 'preserve'
                                  #  - fence STR (def: '```') or FUNC('LINE')->BOOL: code blocks delimiter
                                  #  - tokenizers FUNC_ARR: customize tokenizing. Should not be needed
                                  #  - markers OBJ: custom tokens
                                  #     - start STR (def: '/**')
                                  #     - nostart STR (def: '/***')
                                  #     - delim STR (def: '*')
                                  #     - end STR (def: '*/')
COMMENT-PARSER.file
 ('PATH', FUNC(ERROR, BLOCK_ARR)) #Same for whole file.
COMMENT-PARSER.stream()->IOSTREAM #Same for whole file in streaming mode.
                                  #Takes file lines STR as input and outputs BLOCKs

COMMENT-PARSER.stringify          #Inverse
 (BLOCK[_ARR]|TAG, OPTS)->STR     #OPTS:
                                  #  - indent NUM|STR (def: none)
                                  #  - format 'none', 'align' or FUNC(TOKENS)->STR_ARR

TOKENIZERS ==>                    #Not documented until needed

TRANSFORM                         #FUNC(BLOCK)->BLOCK
COMMENT-PARSER.flow(TRANSFORM_ARR)
 ->TRANSFORM                      #Compose several TRANSFORMs into a single one
COMMENT-PARSER.transforms         #TRANSFORMS
TRANSFORMS.indent(NUM)->TRANSFORM #Indent by NUM characters
TRANSFORMS.align()->TRANSFORM     #Vertical alignment
TRANSFORMS.crlf(STR)->TRANSFORM   #STR is 'LF|CRLF'. Change the newlines

BLOCK|TAG.source                  #Raw STR without the /** */ and leading *, trimmed
BLOCK|TAG.line                    #NUM (0-based). Starting line
BLOCK.description                 #'DESCRIPTION'

BLOCK.tags                        #TAG_ARR
TAG.tag                           #'TAG'
TAG.type                          #'TYPE' ('' if none)
TAG.name                          #'NAME' ('' if none)
TAG.optional                      #BOOL
TAG.default                       #Default 'VAL' (undefined if none)
TAG.description                   #TAG 'DESCRIPTION' ('' if none)

TAG|BLOCK.source                  #SOURCE_ARR
SOURCE.source                     #STR
SOURCE.number                     #NUM. Line number
SOURCE.tokens                     #TOKENS
TOKENS.delimiter                  #'/**', '*/' or ''
TOKENS.tag                        #'@TAG'
TOKENS.type                       #'{TYPE}'
TOKENS.name                       #'NAME'
TOKENS.description                #'DESCRIPTION'
TOKENS.start|end                  #STR. Space at start|end
TOKENS.postDelimiter|Tag|Type|Name#STR. Space between those tokens

TAG|BLOCK.problems                #'ERROR'_ARR