TypeDoc comment parsing

[aciccarello]

As a reference for a possible TSDoc spec, here is how TypeDoc currently parses comments. The short version is that the text content of comments is as markdown. When a tag is encountered, the following text is still parsed as markdown, but tied to the tag name. Inline links are allowed in the body and in tag text.

TypeDoc starts by using TypeScript's getJSDocCommentRanges() method to get the comment string. It parses the comment line by line. If the line starts with an @ symbol, the line is read as a tag. The word following the @ symbol is considered the tag name. @return tags are normalized to @returns. The word following an @param or @typeparam tag is considered the param name and the rest of the line is left as the line content. A hyphen delimiter after the param name is optional. All other tags are stored with the contents of the rest of the line and any following lines until another tag is found. I would recommend changing this parsing to have special handing for tags without any text on the same line as it is often unexpected that text is parsed as part of the previous tag (see the single-line-tags plugin). If there is a three backtick code fence it will not parse for tags until another code fence is found. For this source code, see typedoc/src/lib/converter/factories/comment.ts.

TypeDoc will allow anything to be used as a tag name. There are some special cases though. An @private, @protected, or @public tag will modify a reflection, overriding the modifier on the TypeDoc reflection. An @event tag will change the reflection to an Event kind. The @hidden tag will hide the reflection. We are considering adding @ignore as an alias of @hidden (see TypeStrong/typedoc#198). There is also an @category (see TypeStrong/typedoc#564) though its use is limited.

Within comment text (either the main comment body or in the text of a tag), links are converted into links. The two types of link syntax that TypeDoc supports are [[ReflectionName]] and {@link ReflectionName}. Inline links can alternatively use the @linkcode or @linkplane tag names to indicate whether or not a link should be displayed in monospace. Reflection names are looked up in the project Links can be split by a | or space character to specify a target and a custom caption.

Parsing aspects still to specifiy

• How are the targets of inline links looked up
• defining property descriptions in config objects (i.e. @param config.aProp config property description)