Triple-slash comments for JSDoc

[sandersn]

This PR adds a new triple-slash format for JSDoc comments. It's the same as the C#, Rust and Swift syntax for doc comments.

Motivation

Triple-slash comments have several advantages over multi-line doc comments:

1. They're easier to type and manipulate. Turning

// Some quick documentation here
// But I forgot to make it jsdoc
function foo() { ... }

into triple-slash comments is much easier than the conversion to multi-line comments. Turning one-line to multi-line is actually reasonable, unlike with JSDoc:

/** brevity is the soul of wit */

/**
 * oh wait, I thought of something else to say:
 * 
 * brevity is the soul of wit
 * AND
 * silence is golden
 */

2. Triple-slash comments are stricter and there is a more obviously correct way to indent them. Currently, Typescript produces "reasonable" results for all kinds of badly formatted jsdoc:

/** I started typing here
 *
 *     and then indented to here
 *     typed here for a while
 * went back to here
   forgot to add asterisks
   
       this is a markdown code region, please retain four (4) leading spaces!
 */

Triple-slash comments require a leading /// on each line, and span only from after the /// to the end of the line:

/// I started typing here
///
   /// and then indented to here
///    is interpreted differently then
/// went back to here
Forgetting slashes is a syntax error!
////     this is definitely a markdown code region
    //// this is definitely not

3. As a result, triple slash comments are way easier to parse.

This is just a draft right now. I intend to talk to authors of other tools to see if they are interested in supporting this syntax.

Implementation

The current implementation has quite a bit of duplication. It also has a number of minor fixes that need to happen:

1. Tags stop parsing their text at the end of their comment line.
2. Tags still parse with the same state machine as multi-line comments, so may drop leading * as in /// * markdown bullet point.
3. Leading+trailing whitespace needs to be trimmed.
4. One fourslash test needs to be updated.
5. I need to convert a good variety of existing jsdoc tests to triple slash to see if anything breaks there.

[weswigham]

In C# there's an expectation that these comments parse XML tags within them, like <summary> - that's actually what inspired or own "triple slash references", I'm pretty sure. I'm not sure we want to lead c# devs into thinking we support that whole system... (Nor do I think we actually want to support that).

Other than that, I don't see much of a reason to bother, since it's not like any other JS tools interpret comments like this? Like, I get that there's probably not much harm done by it (expect potentially confusing future SO questions asking why doc tool X doesn't read "doc comments")... But... Eh?

[weswigham]

Oh, also, re: converting types of comments. In vscode at least, ctrl + / will toggle single line, while shift + alt + a will toggle multiline coments; so swapping between the two basic kinds isn't normally so bad (if you're aware of the keybinds).

[mjbvz]

This seems pretty neat!

For the tooling / editor side of things, I have a few questions:

• Would we need a switch so that commands such as toggle line comment in VS Code use ///?

  I guess not since block comments would use regular /* */. Maybe we need a new command, such as toggle doc comment?

• Would we need a setting so that our JS Doc template uses one doc comment syntax or the other?

  Probably not I think, since you have to type /** to trigger the template today but I want to make sure this is the case. We'd likely just add /// as another trigger for the jsdoc template

• Are there any code actions that generate jsdoc comments today and would they need a setting to target the right comment syntax?

• Would we want new on enter rules for /// comments?

  For example, for the following code with the cursor at |:

  /// A thing |
  const a = 1

  Return should probably produce:

  /// A thing
  /// |
  const a = 1

[JacksonKearl]

Would we want new on enter rules for /// comments?

I could see that being annoying if you're only trying to do one line... but maybe if we follow the convention that one enter continues the section, then enter on an "empty" (/// only) line removes it?

OneNote does this for bullets, I think MacOS notes is the same.

[DanielRosenwasser]

@JacksonKearl What do you want to place after the doc comment?

/// Does something
function foo() {
}

[DanielRosenwasser]

Never mind, I'm assuming the declaration is already written 😄

[minestarks]

@sandersn curious, does this mean that when you use //// like in our fourslash tests, those are parsed as JSDoc comments?

[sandersn]

Yes, but fourslash just uses source file text; it doesn't care about any AST. (As far as I know -- I could be wrong.)

Same for any other tool that wants to use ////.

[dhoulb]

Having a "toggle doc comment" feature in VScode would be the killer feature here.

I don't hate the triple slash syntax, but I don't see it being widely adopted. I'm not sure I'd use it personally. Feels like it'll just become a 'quirky' TypeScript thing down the line (that you then have to support forever).

[octogonz]

For a proposal to revamp JavaScript's established doc comment syntax, the 3 motivations above don't seem super compelling. In particular, the Markdown spacing ambiguity is probably a non-issue in practice. For example:

• TSDoc today takes the position of omitting Markdown spacing rules entirely from its grammar, because they are too counterintuitive for technical work. (In cases where correctness matters -- for example with a DocFX pipeline where code comments will eventually end up on a customer-facing website, weeks after you merged your PR, with no quick way to preview the final output.)
• If we optionally accept the more esoteric Markdown syntaxes (which @rbuckton has been working on), personally I wouldn't use it without a realtime preview in VS Code, since CommonMark is pretty much impossible to author correctly without a preview. There's just too many context-sensitive quirks for a causal author to remember, especially with character escapes. Whether /**    example */ is a code block or not is the least of those concerns. :-)

But microsoft/tsdoc#160 (comment) brings up a different motivation that maybe would justify a move to ///. Take this example:

/**
 * Strips the comments from an input string:
 *
 * @example
 * ```ts
 * // prints " some text":
 * console.log(stripComments("/* a comment */ some text");   👈 SYNTAX ERROR
 * ```
 */
function stripComments(code: string): string;

Nesting /* */ is really awkward, whereas nesting /// is not. We encounter this problem rather frequently with doc comments. It's not just academic.

@sandersn this PR raises some other interesting design questions as well:

• Should /// comments otherwise have identical syntax as /** */ comments?
• Or since they look so different, is this an opportunity to dispense with a bunch of other JSDoc baggage such as {@link}?
• Should we maybe even dispense with Markdown in favor of C#-style docs? Maybe too radical, although I fairly enjoyed Sandcastle back in the day!
• Would the compiler then treat /** <reference types="node" /> */ as equivalent to /// <reference types="node" />?
• Since you're proposing to support "Markdown" inside ///, to what extent does it implement CommonMark?

Some test cases for that last question:

/// <!--
/// <reference types="node" />
/// -->

/// ```
/// <reference types="node" />
/// ```

/// \<reference types="node" /> 

[milahu]

push : )

[sandersn]

This experiment is pretty old, so I'm going to close it to reduce the number of open PRs.