0.x can be mostly translated into 1.x one way or another. The idea behind the new config structure is to handle only the most common cases, and provide the fallback for alternative implementation.
By default dotted names like
name.subname.subsubnamewill be expanded into nested sections, this can be prevented by passing opts.dotted_names = false.
Removed This feature is removed but still can be done on top of the parse() output. Please post a request or contribute a PR if you need it.
Set this to false to avoid the default of trimming whitespace at the start and end of each line.
In the new parser all original spacing is kept along with comment lines in .source. Description lines are joined together depending on spacing option
New option:
spacing: "compact"lines concatenated with a single space and no line breaksspacing: "preserve"keeps line breaks and space around as is. Indentation space counts from*delimiter or from the start of the line if the delimiter is omittedspacing: (lines: Line[]) => stringcompletely freeform joining strategy, since all original spacing can be accessed, there is no limit to how this can be implemented. See primitives.ts and spacer.ts
If the following lines of a multiline comment do not start with a star,
joinwill have the following effect on tag source (and description) when joining the lines together:
- If a string, use that string in place of the leading whitespace (and avoid newlines).
- If a non-zero number (e.g., 1), do no trimming and avoid newlines.
- If undefined, false, or 0, use the default behavior of not trimming but adding a newline.
- Otherwise (e.g., if join is true), replace any leading whitespace with a single space and avoid newlines.
Note that if a multi-line comment has lines that start with a star, these will be appended with initial whitespace as is and with newlines regardless of the join setting.
See the spacing option above, all the variations can be fine-tunned with spacing: (lines: Line[]) => string
Set to a string or regular expression to toggle state upon finding an odd number of matches within a line. Defaults to ```.
If set to a function, it should return true to toggle fenced state; upon returning true the first time, this will prevent subsequent lines from being interpreted as starting a new jsdoc tag until such time as the function returns true again to indicate that the state has toggled back.
This is mostly kept the same
New optoins:
fence: '```'same as 0.xfencer: (source: string) => booleansame as 0.x, see parser/block-parser.ts
In case you need to parse tags in different way you can pass opts.parsers = [parser1, ..., parserN], where each parser is function name(str:String, data:Object):{source:String, data:Object}. ...
New options:
tokenizers: []Tokenizeris a list of functions extracting thetag,type,nameanddescriptiontokens from this string. See parser/spec-parser.ts and primitives.ts
Default tokenizers chain is
[
tagTokenizer(),
typeTokenizer(),
nameTokenizer(),
descriptionTokenizer(getSpacer(spacing)),
]where
type Tokenizer = (spec: Spec) => Spec
interface Spec {
tag: string;
name: string;
default?: string;
type: string;
optional: boolean;
description: string;
problems: Problem[];
source: Line[];
}chain starts with blank Spec and each tokenizer fulfills a piece using .source input
One may also convert comment-parser JSON structures back into strings using the stringify method (stringify(o: (object|Array) [, opts: object]): string). ...
Stringifier config follows the same strategy – a couple of common cases, and freeform formatter as a fallback
New Options:
format: "none"re-assembles the source with original spacing and delimiters preservedformat: "align"aligns tag, name, type, and descriptions into fixed-width columnsformat: (tokens: Tokens) => string[]do what you like, resulting lines will be concatenated into the output. Despite the simple interface, this can be turned into a complex stateful formatter, see"align"implementation in transforms/align.ts
Work in progress