Doc should be able to extract "module level" JSDoc

[bartlomieju]

/** This module is intended to be 
 * used with latest deno runtime.
 * Lorem ipsum.
 **/


/** hello */
function foo() {
}

Doc generator should be able to extract first JSDoc and treat it as a "module documentation" - showing it at the top of terminal output or pass it to JSON structure.

CC @ry

[wperron]

Grabbing the first jsdoc comment arbitrarily might lead to some undesired behavior; for instance if a module is implemented in plain js and uses jsdoc to declare type definitions and that's what's at the top of the module, it probably shouldn't be interpreted as module-level doc. Maybe we should instead look at the @module tag rather than simply the first jsdoc encountered -- this is likely only a concern for plain javascript modules.

[ry]

Maybe we should instead look at the @module tag rather than simply the first jsdoc encountered

It's unfortunate that in JavaScript (and especially TypeScript) it often requires extra syntax, extra characters to do the right thing. It has the effect of making the language tedious. Smaller code is worse, you must add boilerplate to make it better. @module is boilerplate. (BTW I'm not questioning the necessity of it - I have no idea - just noting that correct is unfortunately often longer than incorrect.)

[jeremyBanks]

I have seen @fileoverview most often, but apparently @file is canonical JSoc. It would be great if Deno Doc could support this in some form. I'd like to add a brief description at the top of some of my module docs. 🙂

[vovacodes]

I'd like to revive this discussion, I'm happy to take on this issue but we, as a community, need to agree on how we define the module-level comment.

• There were some valid points mentioned against simply grabbing the first JSDoc in the file.
• @module or @file seem quite "boilerplaty", I'd agree with @ry on that.
• JSDoc is generally not a very friendly format for long-form comments that may include markdown - you need to escape a bunch of characters.

There is a very good reason Rust, Dart, and C# adopted /// and //! for doc comments and TSDoc is considering supporting them too, it's super easy to parse and markdown-friendly.
I know we have legacy (JSDoc) that has been working well enough for a lot of people for years but it doesn't look like there is a lot of existing code that uses module-level comments so we could simply embrace the most popular format.

Since we are, effectively, introducing a relatively new concept to the js doc comments why wouldn't we just pick what works and is battle-tested from another existing ecosystem, namely //! from Rust. Among the benefits of such an approach:

• we don't need a fancy parser for that
• we won't accidentally start displaying whatever random JSDoc people put at the beginning of their files, like licenses or types.
• we end up with a doc comment format that is friendly to markdown which a lot of people will end up using if we plan to replace the concept of README with such doc comments.

What do you, folks, think?

[vovacodes]

After more consideration, it probably makes sense to indeed support the @module tag as documented here: https://jsdoc.app/howto-es2015-modules.html . I'll try to look into that

/**
 * This is top-level module documentation.
 * @module
 */

export const foo = 42