Triple slash support (C# style)

[MikeMitterer]

Please support triple slashes
Triple slash documentation is much cleaner in my opinion.
E.g. Dart also supports it: https://www.dartlang.org/guides/language/effective-dart/documentation#do-use--doc-comments-to-document-members-and-types

[octogonz]

I agree that /// is a better design, if we were starting from a clean slate. For example, /// comments can easily be embedded inside other /// comments without any escaping, but */ is rather awkard to handle inside a JSDoc comment.

Unfortunately there are a couple problems with such a change:

• TSDoc aims for "one obvious way" of doing things, versus lots of different equivalent syntaxes for the same thing. This is my personal philosophy as an engineer. But there is also a technical justification, since TSDoc grammar aims to be formalized, unambiguous, and easy to write interoperable parsers for, so every extra grammar rule is expensive to add. (Here I mean "standard" rules, not stuff supported in "lax mode")

• TSDoc aims to be familiar and align with practices already in use today (which is mostly inspired by JSDoc). I've never seen an NPM package that uses /// for its API docs -- but maybe I'm not looking hard enough?

From a non-standard perspective, it would be reasonable to request for the parser library API to accept the raw lines as its input. In the current implementation we remove the /* framing during parsing, so the error line/col will be correct.

Coming from Rust, the triple-slash syntax is used everywhere and I've come to appreciate it a lot more than the usual block-style comments. I think that there's a bit of a difference between allowing line and block comments and adding multiple formats for the documentation itself.

I absolutely agree that the actual @tags should have one syntax. It would be ridiculous to allow aliases like @arg and @param for example, and having just one makes sense. But forcing all of the comments to be block comments feels wrong to me.

There's a reason why languages offer both block and line comments and I think that it doesn't really split the ecosystem to allow both. Consistency within a project can easily be established through linting, and I don't think it requires many mental hurdles to jump through to understand.

[octogonz]

Coming from Rust, the triple-slash syntax is used everywhere and I've come to appreciate it a lot more than the usual block-style comments.

Is there a specific benefit, though, beyond looking more like Rust source code? There are nontrivial costs:

• Everyone who writes a comment parser needs to implement this alternate syntax, even though it is very rarely used.

• The standard will need to specify handling of edge cases (what if some of the lines start with // or //// instead of ///?)

• When people copy code or move source files between projects created by different "comment tribes," they would have to fix up comments. Or else a tool like Prettier would need to add a feature to automatically normalize /// back to the more common /**.

We can do this. They are certainly easier problems than other work we've already done. But what do we get from this investment?

It's nice because:

1. Many documentation lines are only one line long.
2. Most people modify every line of a block comment to start with * anyway.
3. For single-line comments, you don't need to worry about a */ at the end.
4. For multi-line comments, you don't waste an extra line for /** and */.

Also, the case you mentioned: what if someone types /* or /***? It's the same deal; you count it as a doc comment if it has three or more slashes and not otherwise. "Very rarely used" would need backing data and I have a feeling that it would be a welcome change.

Is it worth it? I can't say. If I had more time to spend on this it'd make sense to run a community poll. But I figured I'd add my comments on this because the issue was open and there wasn't that much detail here. :)

[octogonz]

I realize that this proposal would also require separate fixes for each tool that supports TSDoc, since the TSDoc library itself does not find comments within a source file. That job is always handled by the caller (because they do it while parsing API signatures):

For example, our API demo does it like this (using the TypeScript compiler API):

tsdoc/api-demo/src/advancedDemo.ts

Lines 69 to 74 in b2bdf5c

	// True if the comment starts with '/**' but not if it is '/**/'
	return commentRanges.filter((comment) =>
	text.charCodeAt(comment.pos + 1) === 0x2A /* ts.CharacterCodes.asterisk */ &&
	text.charCodeAt(comment.pos + 2) === 0x2A /* ts.CharacterCodes.asterisk */ &&
	text.charCodeAt(comment.pos + 3) !== 0x2F /* ts.CharacterCodes.slash */);
	}

Whereas the TSDoc Playground does it like this (using the Monaco editor control):

tsdoc/eslint-plugin/src/index.ts

Lines 98 to 107 in b2bdf5c

	const textRange: TextRange = TextRange.fromStringRange(sourceCode.text, comment.range[0], comment.range[1]);
	// Smallest comment is "/***/"
	if (textRange.length < 5) {
	continue;
	}
	// Make sure it starts with "/**"
	if (textRange.buffer[textRange.pos + 2] !== '*') {
	continue;
	}

The TypeScript compiler itself provides a bunch of APIs with names like getJSDocType(), getJSDocTags(), etc that are used for refactoring and IntelliSense.

All these parsers would need to be updated to recognize /// as JSDoc. And there will be slight grammar differences, for example this is allowed:

/// ```
/// /* code snippet */
/// ```

Wheres in TSDoc it needs to get escaped like:

/**
 * ```
 * /* code snippet *
 *+/
 * ```
 */

I personally agree that /// is a better comment syntax than /**. If I were a benevolent dictator, I would deprecate /** and force everyone to adopt ///. 😋 But the JavaScript community has already mostly converged on /**. It seems unwise to go against that. And replacing one standard with "two standards" brings its own costs.

Is it worth it? I can't say. If I had more time to spend on this it'd make sense to run a community poll.

We could ask automobile owners: "How do you feel about a switch that lets you move your steering wheel to the left side OR the right side? The same car can drive in any country!"

People might vote yes. It has some marginal value, and nobody's obligated to use it.

But we should also poll the car manufacturers to see if they are willing to build it. 🙂

[orta]

We've been thinking a bit about this on the TS side too: microsoft/TypeScript#39930

[ohnv]

Strong +1 for '///' style comments.

I love commenting stuff. But I also like the code to be reasonably compact. For me, sure, a single /// comment and a 1-line /** comment */ comment is the same. But once you move the two lines...

/// Triple-slash comments on two lines are
/// still pretty compact.
public someProperty: string;

/**
* These comments though suddenly baloon to 4 lines.
* Eeep! Save me
*/
public someProperty: string;

Pedantic, but why would I be a programmer if I wasn't 😎

[octogonz]

The "it's slightly less keystrokes!" argument didn't seem very compelling.

But there is a particularly thorny problem of /** */ that is neatly solved by /// comments: code excerpts.

Consider this example:

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

You will find that this is a syntax error because */ cannot be embedded inside another comment. After a very long deliberation, TSDoc RFC 166 settled on a special + notation that unwraps the following line:

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

It is a clunky solution, but I've become convinced it's the only complete solution to this problem.

Whereas nesting /// comments is trivially easy:

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

However moving from /// to /** seems like a big enough deviation from JSDoc that it might remove the expectation to align with legacy JavaScript comments. So if we went this way, we might also consider bundling it with more radical changes:

1. Making /// the preferred TSDoc syntax, and treating /** */ as a deprecated notation
2. Relaxing the goal for TSDoc to align with JSDoc, and eliminating baggage like {@link} in favor of Markdown links
3. Even replacing Markdown with XML markup like what C# used. XML is more verbose, but it has the significant advantages of (1) having a well-specified grammar with sane escaping mechanisms and (2) providing a baked-in guarantee that custom tags will never break other tool's ability to parse the comment -- the major hangup of Markdown.

As a conversation piece, this is how Sandcastle would represent the above docs:

/// <summary>Strips the comments from an input string:</summary>
/// <param name="code">the input string</param>
///
/// <example>
/// <code lang="ts">
/// // prints " some text":
/// console.log(stripComments("/* a comment */ some text");
/// </code>
/// </example>
function stripComments(code: string): string;

It's verbose. But having personally written a lot of Sandcastle docs back in the day, it does have the upside that you never have to guess how your markup will get rendered on the website. And it's super easy to correctly parse a comment containing unsupported markup.

But... are any TypeScript devleopers not horrified by this prospect? 😁

[buschtoens]

A further advantage of /// is better Tab indentation support. When using /** */, the horizontal (column) offset introduced by the leading  *  is uneven (3 chars), where as ///  is even (4 chars).

This makes authoring multi-line code blocks, e.g. for @example, extremely annoying.

I haven't yet found any setting / extension that fixes this indentation offset in VS Code.

/**
 * The back ticks of the following code fence start at column 3.
 * This means that the first level of indentation starts at column 5.
 *
 * Hitting the `Tab` key always inserts even indentation and thus indents
 * incorrectly.
 * 
 * ```ts
 * const foo = {
 *   expected: true,         // ✅ Col 5: Manual correct indentation by two spaces.
 *  tabPressedOnce: true,    // ❌ Col 4: 1 x `Tab` indents by one space.
 *    tabPressedTwice: true, // ❌ Col 6: 2 x `Tab` indents by three spaces.
 * };
 * ```
 */

[buschtoens]

It seems that prettier-plugin-jsdoc adds support for auto-formatting code fences. So while Tab is still broken, at least saving a file will fix the code block, if auto-format is enabled.

// .prettierrc
{
  "plugins": ["prettier-plugin-jsdoc"],
  "tsdoc": true
}