Differentiating what is a documentation comment

[tmcw]

trafficstars

Intent

Code comments are heavily used as things other than documentation: for TODOs, for notes to self, for swear words, and sometimes more. We don't want to accidentally include comments that are not documentation in documentation.

Prior art

JSDoc: documentation comments begin with two asterisks *.

/**
  * Documentation comment
  */

getdocs comments aren't differentiated except by, maybe, location?

// :: (number, number) → number
// Add two numbers

rustdoc: documentation comments begin with ///

/// An example method.
///
/// Sup.

godoc comments aren't differentiated

// ServeHTTP dispatches the handler registered in the matched route.
//
// When there is a match, the route variables can be retrieved calling
// mux.Vars(request).

Concerns

• If we use the same documentation start as JSDoc, then we'll automatically attempt to document all JSDoc. This format is not JSDoc, so many of those comments will fail.

[jamiebuilds]

Is there a need to differentiate them? It seems like using their positions would be enough.

// function declaration comment
// @param a {number} description
function foo(a) {...}

[anandthakker]

I think it'd be nice to be able to use both multiline and single line comments, and for multiline, both:

/*
 * framed
 */

and

/*
bare
*/

[tmcw]

getdocs & godoc don't care to differentiate comments, and I'm cool with that - my only concern is the chance that someone writes a comment as a note-to-self and it gets included in documentation - like there wouldn't be a way to write a note to self that sits above a function and doesn't get included as documentation.

Which is probably fine, or still a net gain? I think 'any comment that precedes a chunk of exported code' being documentation is doable.

[anandthakker]

I think 'any comment that precedes a chunk of exported code' being documentation is doable.

Yeah, maybe with the addition of (a) a way to explicitly omit a chunk of documentation (@notdocs or something), and (b) a way to explicitly include a chunk that isn't directly attached to a chunk of exported code?

(b) would need some mechanism to specify where such a chunk should be attached... maybe not necessary?

[arv]

To clarify, godoc comments must start with the function name.

// Data returns the good stuff.
func Data() {}