@module does not add "All symbols in the file"

[rbong]

JSDoc standard:

All symbols in the file are assumed to be members of the module unless documented otherwise.

This does not happen.

Mentioned in #234 but there is no specific issue.

[alekbarszczewski]

👍 This would be awesome - currently it's not possible to document a library with documentation.js since it puts all methods/members of modules in to the project root instead of grouping them in modules.

[tmcw]

Like the rest of the JSDoc properties, I'm very open to PRs implementing the rest of this.

That said, would want to clarify this a bit:

JSDoc has this concept called modules that, as far as I can tell, doesn't actually relate 1:1 to any concept in JavaScript - not ES6 modules, not CommonJS modules, not files. I think this is mainly because JSDoc is old enough that it predates, well, all of those, even the rise of CommonJS. So I've been hesitant to include JSDoc module support because, as far as I can tell, it doesn't reliably mean anything. Some code being 'in the color module' doesn't say "you can do require('color') or require('parent/color') or, really, anything at all: as far as I can tell, the JSDoc module construct doesn't actually have explanatory value. It does have organizational value, and for that - there's the configuration file that's available, which, imho, is more useful than JSDoc's module system, because it allows for plain-english titles (no "no spaces" restriction) and it allows you to order the output.

[alekbarszczewski]

@tmcw I can't find proper way to configure documentation by using documentation.yml. For example in my code I have documented class Store with some methods. It's included in documentation correctly. I have also some objects defined in file types.js. Without configuration those objects are listed on the top level of documentation, just below the Store. With config file (see screen) they are grouped in "TYPES" section but:

1. style of "types" header is different from "Store" style (see screen)
2. actually documentation of all objects in "types" section is missing. For example MethodName links to http://localhost:4001/#methodname but that section is missing from docs content

I understand your concerns, but I guess most users want to document their libraries. Libraries consist of (usually) some exported modules. So there must be a way to document what your library is exporting. documentation.yml would be a way to overcome missing support for jsdoc modules, but it seems it does not work. Anyway in my opinion there should be a way to namespace/group modules from within a code - this is the biggest advantage jsdoc that you are documenting code, not writing a documentation. But anyway config file is a good idea to extend functionality.

[tmcw]

To clarify this a little bit: if your module has types, and a Store, what is it exporting? Like if someone writes var theValue = require('your-module');, what value is stored in theValue? Is it theValue.types.someType, or something else? Essentially, the code structure internally has types.js defining the types, but how is this reflected in the external-facing API of the module?

My issue is the concept of a JSDoc 'module' doesn't seem to mean anything that would be of value to someone who uses a library. It doesn't correspond to any actual code-level concept. If it were, for instance:

var myLib = require('my-lib');
myLib.types.foo = 2;

Then types isn't a module, it's just an object, and there's no reason I can see for treating some objects as objects and others as modules.

[alekbarszczewski]

// types.js
export const MyType = 123

// store.js
export class Store {}

// index.js
export Store from './store'
export * as types from './types'

// usage
import { Store, types } from 'my-lib' 

Expected docs:

• Store
  • storeMethod1
  • storeMethod2
• types
  • MyType

Keep in mind that (at least in my case) I want docs for end-user of my lib, so it should be similar to what user imports in his project. MyType is just an example - in fact it could be even a class MyClass, in types "module" (call it object, namespace or as you want).

[alexvicegrab]

I have the very same issue with the configuration file. The headings are nice, but documentation inside disappears. My objects are exported classes.

Thanks in advance for looking into this!

[alexvicegrab]

I've also tried to recreate one of the tests in the test suite of documentation, involving:

test('config with nested sections', async function() {
  var file = path.join(__dirname, 'fixture', 'sections.input.js');
  const out = await documentation.build([file], {
    config: path.join(__dirname, 'fixture', 'sections.config.yml')
  });
  const md = await outputMarkdown(out, {});
  expect(md).toMatchSnapshot();x
});

Where sections.input.js is:

/**
 * This function is first
 */
function first() {}

/** */
class AClass {
  /**
   * forgot a memberof here... sure hope that doesn't crash anything!
   * @method first
   */
  first(x, y) {}

  /**
   * shares a name with a top level item referenced in the TOC... sure hope
   * that doesn't crash anything!
   */
  second() {}
}

/**
 * This class has some members
 */
function second() {}

/**
 * second::foo
 */
second.prototype.foo = function(pork) {};

/**
 * second::bar
 */
second.prototype.bar = function(beans, rice) {};

/**
 * This function is third
 */
function third() {}

And section.config.yml is:

toc:
  - name: Alpha
    children:
      - third
      - first
  - name: Bravo
    description: Contains a subsection!
    children:
      - name: Charlie
        description: Second is in here
        children:
          - second

I see the following output, which is to my eyes unexpected:

[alexvicegrab]

Actually, this may be to some extent bypassed by this example:
https://github.com/simple-statistics/docs/blob/gh-pages/documentation.yml

Still, the documentation of documentation, and the tests should be updated to reflect this possibility.

But the "children" property bit in https://github.com/documentationjs/documentation/blob/master/docs/CONFIG.md is still broken

[DonGissel]

Has there been any development on this by anyone? I'm trying to document a big project built around some 50 utility files that each export a lot of discrete functions, and they're all bundled together in the index no matter what I do. Refactoring the code to classes isn't an option (nor would I want to), and no combination of JSDoc-tags seems to yield the result I'm after. Which is a nice, hierachical, flat overview of the all files in my project, indexed by their folder/filename and each exported symbol/method/class/whatever listed below as an expandable/collapsible list.

I'd like to help, I really would, but I haven't got the faintest idea about how to go about this. If anyone had made any progress on it, in a fork or a development branch, I'd be happy to take a look and see if I could contribute.