Support for additional comment styles

[Gerrit0]

Search Terms

triple slash comments, c# style documentation, comment style

Problem

TypeDoc doesn't support relatively common comment styles

Suggested Solution

Add a new option: commentStyle which determines how TypeDoc searches for comments:

• JSDoc (default) - /** ... */
• Block - /* ... */
• TripleSlash - /// ...
• All - //, ///, /* */, /**

This suggestion was previously rejected (see #963), but my stance on it has completely changed having used a language which uses /// comments. They are much nicer for dealing with embedded codeblocks that contain block comments.

At the same time, for JSDoc and Block style comments, this should add support for the escaping mechanism used by TSDoc.

Cross linking:

• Triple slash support (C# style) microsoft/tsdoc#160
• RFC: Escaping doc comments inside doc comments microsoft/tsdoc#166
• Triple-slash comments for JSDoc microsoft/TypeScript#39930
• Recognize more comment styles #963

[Gerrit0]

this should add support for the escaping mechanism used by TSDoc.

I looked at implementing this today, and... there still isn't consensus on the TSDoc side. Using + to continue a line seems somewhat useful, but since marked won't add <br>, in most cases you can just do this...

For now, I'm just going to implement support for *\/ being parsed as */. If someone asks for support for the + line continuation, I'm certainly not opposed to it.

See: microsoft/tsdoc#166

[nex3]

If someone asks for support for the + line continuation, I'm certainly not opposed to it.

FWIW I would really like to see TypeDoc align with the TSDoc spec not just here, but as close to 100% as possible. I need to write docs that work well on both my website (which uses TypeDoc) and in users' IDEs (which follow the TSDoc spec), so every place the two don't align means a degraded experience for one of the two.

[Gerrit0]

not just here

This implies that the + escaping mechanism is a TSDoc standard, which is not true. Try putting the following into the official playground https://tsdoc.org/play

/**
 * Here is a bunch of text which is starting to get long so I want to
 *+ wrap the line
 */

I think having an escaping mechanism like this is potentially useful, but given that it hasn't been standardized, wasn't going to spend time implementing it when nobody's trying to use it today.

users' IDEs (which follow the TSDoc spec)

As far as I know, there is no editor which follows the TSDoc spec. Each one makes a best effort to display comments as the user intended, but no editor implements strict support for TSDoc, since only a tiny percentage of documentation comments conform to TSDoc. Until less than a week ago, even VSCode didn't support @example blocks with example text and a code block because their support assumed JSDoc-style @example blocks, where everything is code, unless the <caption> tag is used.

If you want a documentation generator which forces you to strictly follow TSDoc, you should use https://api-extractor.com/. The goal of this project is to make writing documentation easier, not force a specific style or format on developers. TypeDoc once the TSDoc project is done should be compatible with TSDoc, but it will not force its users to use TSDoc. In fact, this issue, adding support for /// comments will be yet another difference between TypeDoc and TSDoc, until and unless the RFC which has seen effectively no activity for nearly 2 years suddenly happens.