Terse documentation

[tmcw]

As @marijnh https://github.com/marijnh/getdocs and @IvanSanchez's https://github.com/IvanSanchez/Leafdoc indicate, there's a significant faction that wants more compact documentation syntax than JSDoc.

As far as "how it's terse":

Comment style

Both projects consume // C++ style comments as well as or instead of /** comments. It's code-wise simple to support one as well as the other, but the JSDoc /** style makes it explicit which comments will be output in documentation and which will not be. If we supported // comments, my best guess is that we'd put in a rule that said "if this comment block contains at least one tag, treat it as documentation"

Short params syntax

This is in getdocs:

// :: (number, number) → number
// Add two numbers
export function plus(a, b = 2) {
  return a + b
}

This is roughly equivalent to

/**
 * Add two numbers
 * @param {number} a
 * @param {number} [b=2]
 * @returns {number}
 */
export function plus(a, b = 2) {
  return a + b
}

But it expresses only types, rather than param descriptions, and refers to params by their index in the arguments array rather than their name.

I wonder if we could do something like a @params tag that split the difference:

/**
 * Add two numbers
 * @params ({number} a, {number} [b=2]) -> {number}
 */
export function plus(a, b = 2) {
  return a + b
}

Leafdoc also does a short arguments / return value syntax, like

/*
🍂method on(type: String, fn: Function): this

Note that both of these approaches are super close to type annotations - Leafdoc's are so close to Flow annotations that I'd argue they should be Flow annotations.

Multiple comments on one line

From Leafdoc:

// 🍂namespace Math; 🍂method sum(a: Int, b: Int): Int ; Returns the sum of two numbers

As far as I know, the ; character isn't used in JSDoc syntax, but I would need to look again. I'm cool with a delimiter to avoid newlines, but it isn't something I'd personally use, since it's similar to bunching lots of source code on the same line; moving complexity around.

[jfirebaugh]

Personally, I think using inference based on Flow annotations hits the sweet spot in terms of concision, avoiding Yet Another Type Annotation Syntax, and taking best advantage of the tooling ecosystem.

/** Add two numbers */
export function plus(a: number, b: number = 2): number {
  return a + b
}

Coincidentally, this is exactly what documentation.js aims to support!

What this doesn't give you is parameter descriptions -- but all the other examples above don't have that either. If you want to describe the parameters (which I think for most real world functions is good practice), JSDoc gives you that option, and with documentation.js you don't have to sacrifice type or default value inference.

/**
  * Add two numbers
  * @param a - the first one
  * @param b - the second one
  */
export function plus(a: number, b: number = 2): number {
  return a + b
}

[marijnh]

I considered going with Flow-style annotations, but that would lock me into using a preprocessor even after Node starts supporting enough of ES6 to run my code, and make it impossible to have tools that understand just ES6 without extensions work with the code.

[mourner]

Comment-type Flow annotations are well-established now, could we support those too?

[jfirebaugh]

http://flowtype.org/blog/2015/02/20/Flow-Comments.html

👍

[tmcw]

Okay: I think the action coming out of this ticket is Flow Comments support, and that is captured in #306. Feel free to post on this with any new thoughts but going to close this with #306 as a follow-up.