Markdown lists.

[DylanVann]

It would be useful to be able to include lists in doc comments:

/**
 * This module does:
 *
 * - A thing.
 * - Another thing.
 * - One more thing.
 */

[csr632]

How can monaco(vscode) render lists already?

[futagoza]

@csr632 It has a built-in JSDoc comment parser that puts the tag content through a markdown to HTML transformer. In fact, I'm pretty sure it has support for most markdown features.

[octogonz]

Right, Monaco's default styler implements a scanner that recognizes various constructs that are commonly found in JavaScript/TypeScript doc comments. Of course, other editors like WebStorm may parse these comments differently. Whereas TSDoc's goals include establishing a rigorous spec that would enable various tools to parse doc comments, and agree on the interpretation. (For example, is <!-- {@link X} --> a visible link or not? What about \{@link X}? What about <b>{@link X}</b>? Today different tools have very different opinions.)

[iansan5653]

Definitely agree with this - a common use case for me is documenting string union types, like this one:

/**
 * Open a file.
 * @param path - the path to the file.
 * @param mode - the file-opening mode to use. Possible values include:
 * 
 *  - `"w"` - basic 'write' mode; allows editing.
 *  - `"w+"` - advanced 'write' mode; allows editing and creates the file if it
 *    doesn't exist.
 *  - `"r"` - basic 'read' mode; allows reading but not editing.
 */
function openFile(path: string, mode: "w" | "w+" | "r"): string {
  //...
}

Of course, in many instances it might be better to use an enum and document each member, but sometimes that's too complex for a simple union, or the union might be pulled from something else (ie by using keyof).

[rbuckton]

The problem I see currently is that the TSDoc emitter doesn't emit DocSoftBreak, so single-line breaks are removed:

    /**
     * Compares this value with another value:
     *
     * - A negative value indicates this value is lesser.  
     * - A positive value indicates this value is greater.  
     * - A zero value indicates this value is the same.  
     *
     * @param other The other value to compare against.
     * @returns A number indicating the relational comparison result.
     */

However the "docComment" written to the API json file looks like this:

"docComment": "/**\n * Compares this value with another value:\n *\n * - A negative value indicates this value is lesser. - A positive value indicates this value is greater. - A zero value indicates this value is the same.\n *\n * @param other - The other value to compare against.\n *\n * @returns A number indicating the relational comparison result.\n */\n",

which looks like the following after a round-trip through the TSDoc parser and emitter:

/**
 * Compares this value with another value:
 *
 * - A negative value indicates this value is lesser. - A positive value indicates this value is greater. - A zero value indicates this value is the same.
 *
 * @param other - The other value to compare against.
 *
 * @returns A number indicating the relational comparison result.
 */

[octogonz]

@rbuckton The word-wrapping is tracked by issue #200.

[rbuckton]

From the linked issue, it seems the current behavior to trim insignificant whitespace is the culprit. The problem, as I see it, is that TSDoc's parser is making assumptions about what kind of whitespace is significant that is inconsistent with what Markdown considers to be insignificant whitespace.