es-joy@es-joy/jsdoccomment
This project aims to preserve and expand upon the
SourceCode#getJSDocComment functionality of the deprecated ESLint method.
It also exports a number of functions currently for working with JSDoc:
API
parseComment
For parsing comment-parser in a JSDoc-specific manner.
Might wish to have tags with or without tags, etc. derived from a split off
JSON file.
commentParserToESTree
Converts comment-parser AST to ESTree/ESLint/Babel friendly AST. See the "ESLint AST..." section below.
estreeToString
Stringifies. In addition to the node argument, it accepts an optional second
options object with a single preferRawType key. If you don't need to modify
JSDoc type AST, you might wish to set this to true to get the benefits of
preserving the raw form, but for AST-based stringification of JSDoc types,
keep it false (the default).
jsdocVisitorKeys
The VisitorKeys
for JsdocBlock, JsdocDescriptionLine, and JsdocTag. More likely to be
subject to change or dropped in favor of another type parser.
jsdocTypeVisitorKeys
Just a re-export of VisitorKeys
from jsdoc-type-pratt-parser.
getDefaultTagStructureForMode
Provides info on JSDoc tags:
nameContents('namepath-referencing'|'namepath-defining'| 'dual-namepath-referencing'|false) - Whether and how a name is allowed following any type. Tags without a proper name (valuefalse) may still have a description (which can appear like a name);descriptionAllowedin such cases would betrue. The presence of a truthynameContentsvalue is therefore only intended to signify whether separate parsing should occur for a name vs. a description, and what its nature should be.nameRequired(boolean) - Whether a name must be present following any type.descriptionAllowed(boolean) - Whether a description (following any name) is allowed.typeAllowed(boolean) - Whether the tag accepts a curly bracketed portion. Even without a type, a tag may still have a name and/or description.typeRequired(boolean) - Whether a curly bracketed type must be present.typeOrNameRequired(boolean) - Whether either a curly bracketed type is required or a name, but not necessarily both.
Miscellaneous
Also currently exports these utilities:
getTokenizers- Used withparseComment(its main core).hasSeeWithLink- A utility to detect if a tag is@seeand has a@link.commentHandler- Used byeslint-plugin-jsdoc.commentParserToESTree- Converts comment-parser AST to ESTree/ESLint/Babel friendly AST.jsdocVisitorKeys- The VisitorKeys forJSDocBlock,JSDocDescriptionLine, andJSDocTag.jsdocTypeVisitorKeys- VisitorKeys forjsdoc-type-pratt-parser.defaultNoTypes= The tags which allow no types by default:default,defaultvalue,description,example,file,fileoverview,license,overview,see,summarydefaultNoNames- The tags which allow no names by default:access,author,default,defaultvalue,description,example,exception,file,fileoverview,kind,license,overview,return,returns,since,summary,throws,version,variation
ESLint AST produced for comment-parser nodes (JsdocBlock, JsdocTag, and JsdocDescriptionLine)
Note: Although not added in this package, @es-joy/jsdoc-eslint-parser adds
a jsdoc property to other ES nodes (using this project's getJSDocComment
to determine the specific comment-block that will be attached as AST).
JsdocBlock
Has the following visitable properties:
descriptionLines(an array ofJsdocDescriptionLinefor multiline descriptions).tags(an array ofJsdocTag; see below)inlineTags(an array ofJsdocInlineTag; see below)
Has the following custom non-visitable property:
delimiterLineBreak- A string containing any line break afterdelimiter.lastDescriptionLine- A numberendLine- A number representing the line number withend/terminaldescriptionStartLine- A 0+ number indicating the line where any description beginsdescriptionEndLine- A 0+ number indicating the line where the description endshasPreterminalDescription- Set to 0 or 1. On if has a block description on the same line as the terminal*/.hasPreterminalTagDescription- Set to 0 or 1. On if has a tag description on the same line as the terminal*/.preterminalLineBreak- A string containing any line break beforeterminal.
May also have the following non-visitable properties from comment-parser:
description- Same asdescriptionLinesbut as a string with newlines.delimiterpostDelimiterlineEndinitial(fromstart)terminal(fromend)
JsdocTag
Has the following visitable properties:
parsedType(thejsdoc-type-pratt-parserAST representation of the tag's type (see thejsdoc-type-pratt-parsersection below)).typeLines(an array ofJsdocTypeLinefor multiline type strings)descriptionLines(an array ofJsdocDescriptionLinefor multiline descriptions)inlineTags(an array ofJsdocInlineTag)
May also have the following non-visitable properties from comment-parser
(note that all are included from comment-parser except end as that is only
for JSDoc blocks and note that type is renamed to rawType and start to
initial):
description- Same asdescriptionLinesbut as a string with newlines.rawType-comment-parserhas this named astype, but because of a conflict with ESTree usingtypefor Node type, we renamed it torawType. It is otherwise the same as incomment-parser, i.e., a string with newlines, though with the initial{and final}stripped out. SeetypeLinesfor the array version of this property.initial- Renamed fromstartto avoid potential conflicts with Acorn-style parser processing toolsdelimiterpostDelimitertag(this does differ fromcomment-parsernow in terms of our stripping the initial@)postTagnamepostNamepostType
JsdocDescriptionLine
No visitable properties.
May also have the following non-visitable properties from comment-parser:
delimiterpostDelimiterinitial(fromstart)description
JsdocTypeLine
No visitable properties.
May also have the following non-visitable properties from comment-parser:
delimiterpostDelimiterinitial(fromstart)rawType- Renamed fromcomment-parserto avoid a conflict. See explanation underJsdocTag
JsdocInlineTag
No visitable properties.
Has the following non-visitable properties:
format: 'pipe' | 'plain' | 'prefix' | 'space'. These follow the styles of link or tutorial.pipe:{@link namepathOrURL|link text}plain:{@link namepathOrURL}prefix:[link text]{@link namepathOrURL}space:{@link namepathOrURL link text (after the first space)}
namepathOrURL: stringtag: string. The standard allowstutorialorlinktext: string
ESLint AST produced for jsdoc-type-pratt-parser
The AST, including type, remains as is from jsdoc-type-pratt-parser.
The type will always begin with a JsdocType prefix added, along with a
camel-cased type name, e.g., JsdocTypeUnion.
The jsdoc-type-pratt-parser visitor keys are also preserved without change.
You can get a sense of the structure of these types using the parser's tester.
Installation
npm i @es-joy/jsdoccommentChangelog
The changelog can be found on the CHANGES.md. <!--## Contributing
Everyone is welcome to contribute. Please take a moment to review the contributing guidelines. -->
Authors and license
Brett Zamir and contributors.
MIT License, see the included LICENSE-MIT.txt file.
To-dos
- Get complete code coverage
- Given that
esqueryexpects arightproperty to search for>(the child selector), we should perhaps insist, for example, that params are the child property forJsdocBlockor such. Where:has()is currently needed, one could thus instead just use>. - Might add
trailingforJsdocBlockto know whether it is followed by a line break or what not;comment-parserdoes not provide, however - Fix and properly utilize
indentargument (challenging foreslint-plugin-jsdocbut needed forjsdoc-eslint-parserstringifiers to be more faithful); should also then use the proposedtrailingas well