Cleaner Documentation Comments with ///

[pouyakary]

🔍 Search Terms

"comment", "jsdoc", "documentation", "doc"

✅ Viability Checklist

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
• This isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

The JSDoc format is both hard to write, and hard to read. More than that it is very messy and designed for a world where there is no compiler present. In the other worlds, languages like Go and Dart have such powerful, and at the same time more beautiful documentation comments that after working with them revisiting TypeScript has become a nightmare of mine. So my suggestion is to employ a better documentation comment, the ///.

📃 Motivating Example

While to some people TypeScript is an improvement to existing JavaScript projects, for some (which I believe is the most) it was the initial language and there was types from the ground up. And thus all the @param parts of the documentation tool are somewhat redundant and a bit ugly to be honest when compared to languages like go where simplicity is the rule. There you simply write a comment above a function and that becomes the function's documentation, that easy. Or in dart, there is a /// comment that has the same semantics, but it also provides a [ClassName] grammar which links to the name of another class. Markdown like and very basic.

Why shouldn't TypeScript have such elegant documentations? You could say:

/// Returns the sum of `a` and `b`
function add(a: number, b: number): number {
   return a + b;
}

Instead of

/**
 * Returns the sum of two numbers
 * @param {number} a the first number
 * @param {number} b the second number 
 */
function add(a, b) {
   return a + b
}

There are somethings here worth noticing:

1. JSDoc has redundancies such as the @param. Usually, all we want to know from @param is the type. When the language has the type, then this becomes redundant. It is much more pleasant that we define something in the comment like:

/// Gets the `n`th root of the number `x`
function root(x: number, n: number): number {

2. /** feels old! Sorry but it matters, and I hope that you agree, TypeScript is a modern language, it has the most advanced type system in the world, it works on cutting-edge compiler architecture and design, and then it has the comment look of the dark ages. Why should it be such? Why can't we have the beautiful ones that are really easy to write and easy to edit (you can enable multiple coursers in vscode and make a normal comment a documentation comment, or the other way, but good luck doing that with JSDoc)

3. It's called JSDoc! It itself says I'm not the TypeScript doc! TypeScript deserves much more!

4. Because editing /// is easier, making tools for it is also easier. I have made an extension for justifying comments so that they are easy to read, uniform, and easy to write. It was so easy to make that for the /// / // comments, but for JSDoc, it was really hard. (I still haven't figured out what should I do) and if TypeScript joins this party, I can make tools like this for my workflow way more easier. And I believe others will too. It is important to enable the community in making tools for what they do. This is an example of a comment justified in Go. I hope that you find it beautiful, and then I can ask: Don't you like to write a comment this clean in TypeScript?

// Compare  compares  equality  of two values
// and returns  a  numeric  value  describing
// their  equality  or  greater  less or less
// than states. -1 if the left is lesser than
// right,  0 if they are equals and 1 for the
// other purpose.
func Compare(a, b computable.Value) computable.Value {

💻 Use Cases

1. Way easier for users to write
2. Way easier for developers to make extensions and tools for
3. Way nicer code to read and navigate
4. Denser in size and therefore more screen real estate + less documentation reading
5. Made for TypeScript and not redundant
6. Easier to maintain in the big projects

[snarbies]

FWIW unless you have tooling that needs to see the @param tags, this gets you most of the way there.

/** Returns the sum of two numbers */
function add(a: number, b: number) {
   return a + b
}

Personally, I'd prefer a simpler syntax that allows params without tags if you like, but in general supports tags the same as the current design. Something like this.

/// Returns the sum of two numbers
/// a - the first number
/// b - the second number 
/// @deprecated
function add(a: number, b: number) {
   return a + b
}

[pouyakary]

@snarbies yes I know that, but my reasoning was to show the nature of it. That it is because of this, and if we move to a more elegant system is better because exactly we don't need proms anymore.

[snarbies]

You don't need them now, was my point.

[pouyakary]

I can remove that part from my point, but it still remains that /// are nicer to write and read.

[nmain]

It's called JSDoc! It itself says I'm not the TypeScript doc! TypeScript deserves much more!

It's called JSDoc because it predates Typescript. This is important more more than just historical reasons; it means that many tools other than Typescript also support JSDoc. Even if those other tools can't understand the type annotations, they can still parse the rest of the comments. Switching to /// would greatly decrease compatibility and interoperability with other tooling.

[pouyakary]

@nmain I'm not saying this is a replacement, I'm saying that this can be another flavor. If anything, JavaScript can simply be defined in letting the developer have options. It has most features most languages have because it is the only common place where everyone comes and write code. So why should it force only one comment style for documentation? I think it would be great to have this alternative because I don't like /**, and then you can keep using /** so that your tooling won't break. It's the essence of web, you get to do it how you wish to do.

[pouyakary]

To be honest I'm a little surprised by the reactions. What I'm trying to say is to just "recognize" an alternative (and preferred) comment style that is "already" implemented and supported, to be a documentation comment as well as the /** for the JSDoc.

For all the years I have seen code, the /* ... */ was so rare to actually spot in code. Most people prefer the ergonomics of // comments. I only see the /* ... */ pattern where people want to disable a portion of a code, or for the copyright templates that they have copied from licenses written in many decades ago. And writing documentation comment is one of those things that at least I do like 20% of my time. I think for what I do 20%-30% during my day, a bit more ergonomics is a huge difference, given the fact that this ergonomics harms absolutely no one, breaks no feature, imposes nothing extra on the runtime, and is probably one of the easiest features to request wouldn't it be logical to ask it?

I honestly don't get your comments and I mean no one anything bad, it's not a nonsense request: many respected programming languages support it. It's not harming anyone in anyways, breaks no feature, changes nothing in the language, poses no long research/development period on the team (it's probably a one day task, and I think I can even implement it myself and give a PR) and I honestly don't get why should anyone try to stop it from happening. What will you get out of stopping others from having a harmless inexpensive feature?

[xiBread]

/// is already used for triple-slash directives plus I don't see the point in adding an alternative when the existing already suffices. All it's going to do is cause confusion and deviate from the standard; not to mention the amount of tools that are now going to have to add support for this when everyone is already using /** */.

[snarbies]

Please don't take people disagreeing with you personally. People are meant to examine issues here. If somebody has a hard time understanding the benefit, it's natural for them to say so and it's incumbent upon you to articulate why the investment is worthwhile. Plus, any feature, even a teensy tiny little feature, takes non-trivial time and effort to develop, almost always more than it seems at first blush. And any feature can have non-obvious consequences.

Most people use an IDE, and the formatting of /** */ documentation mostly just takes care of itself. I'm just not seeing a meaningful ergonomic issue and I genuinely can not see value in taking development time away from something else to implement a feature with a benefit that is somewhere between dubious and non-existent.

Adding a second syntax means everyone has to choose one. It creates the opportunities for style/convention wars, adds additional work for people creating documentation tooling, or creates a situation where somebody chooses one style and then finds out after writing several thousand lines of code that a tool in their chain doesn't like that comment style. There is quite a lot of software out there that only understands what we currently have. Fractures in the ecosystem, even small ones, come with a real cost.

All other things being equal, I'd have preferred /// style comments from the get. But in the present, it might seem trivial for you in your situation, but that doesn't mean that it won't create problems for others that are potentially greater than what it solves for you.

Not trying to rain on your parade. Just trying to convey to you that what you're asking for is not as trivial as it might seem.

[MartinJohns]

Related: microsoft/tsdoc#160

[pouyakary]

Closing since it is a duplicate of #160