Modules

[tmcw]

JSDoc has its own idea of modules, which I've discussed before - essentially

• JSDoc modules are not CommonJS or ES6 modules.
• I'm unconvinced that JSDoc modules are a good thing. There are 2 concepts in JavaScript:
  • Actual modules, like things you install with npm and include with require or import
  • Membership of one object versus another. Foo.bar.baz.
• JSDoc modules are neither of those things, and I can't find any way in which they're actually helpful to the end user: 99% of the cases where documentation.js users want modules to work, what they're really talking about is membership.

I should, though, try to figure out whether:

• If you are, for instance, running documentation over a lerna or otherwise new-wave modular project, should we make it possible to document multiple real modules at the same time?
• Am I missing some value of the JSDoc module concept? Is it useful or sensical in some way that I just don't understand yet?

[jamiebuilds]

It makes most sense to me to limit the spec to what JS provides for modules (not including commonjs). I don't see a lot of value in doing anything else.

As for membership of objects, I think this is why JS needs a namespaces concept like seen in TypeScript.

[autra]

It makes most sense to me to limit the spec to what JS provides for modules

+1

Actual modules, like things you install with npm and include with require or import

I'd just say "like things you include with import". Because for the example of npm, a package is not one module. It's as many modules as there are files (you don't need to use the entrypoint defined in the package.json, you can import individual files if you want).

So, as a lib dev, I'd expect a dx compliant engine to find and document all the reachable modules from the entrypoints I invoked it with (entrypoints could be a single file, or actually a directory to recursively scan if I expect someone would want to import some of my package js files individually).

Optionally, it could discover my entrypoints from package.json and document its structure (with links to individual modules), but I'm pretty sure it should not be in the spec, as it is tied to an implementation detail of npm.

So if I give a dx compliant doc engine this entryPoint:

// Main.js

export * as myfoo  from 'Core/reticulation/foo'; // all named export, but not the default
export { helloMethod } from 'Core/greetings/world';
export Bar from 'module1/bar'; // default export

I'd expect the toc to be something like:

My Lib

Core

• reticulation/foo as myfoo
  • namedExport1
  • namedExport2
  • basically all the export stuff in foo.js
• greetings/world
  • helloMethod

module1

• bar
  • default as Bar

Nesting levels is up to individual engines. I'd like it to be configurable, so reticulation could start a new subsection if needed or so I could have a flat structure. That being said, I think the spec should require to have the full path somehow (instead of just the "leaf" name), because as a user, I need to know how to import foo for instance (would be import something from 'my-lib/Core/reticulation/foo'). Not sure if this is clear :-)

Last but not least, the engine should detect the type of the exports and document them in individual file pages. So that:

function helloWorld() {}
export helloWorld;

or

export function helloWorld() {}

or maybe even

var helloWorld = function() {}

would yield the same doc, because essentially they are the same from the importing side POV. dx engines should know that it is a function in this trivial case (inference might not be always possible). Not sure if this should be a MUST or a SHOULD though :-)

WDYT of this?