Currently when displaying an index of modules, we extract the module JSDoc tag from the default module in a path and display that as a summary.
If the dir doesn't have a default module, we display nothing, which makes it hard to navigate large collections of modules (like std). We need a mechanism/convention to allow this to be documented.
Options I can think of:
_mod.md/_index.md/_doc.md - contains the markdown to be used to provide a summary.
Extract the first non-header paragraph of a README.md in the dir as a summary.
_index.json/_mod.json/_doc.json - Contains a JsDoc object which is used to determinate what to display (which could also be rendered as the readme for the path as well, displayed in full markdown like we do when viewing a module).
Do nothing...
In writing them down, I like the _doc.json solution the best, as it would solve a few problems, and we can add the JSON-Schema to the editor extension to help people author the document, though authoring markdown in JSON is yucky. We could of course support more than one, like the _doc.json but then try the README.md if not present.
Currently when displaying an index of modules, we extract the module JSDoc tag from the default module in a path and display that as a summary.
If the dir doesn't have a default module, we display nothing, which makes it hard to navigate large collections of modules (like
std). We need a mechanism/convention to allow this to be documented.Options I can think of:
_mod.md/_index.md/_doc.md- contains the markdown to be used to provide a summary.README.mdin the dir as a summary._index.json/_mod.json/_doc.json- Contains a JsDoc object which is used to determinate what to display (which could also be rendered as the readme for the path as well, displayed in full markdown like we do when viewing a module).In writing them down, I like the
_doc.jsonsolution the best, as it would solve a few problems, and we can add the JSON-Schema to the editor extension to help people author the document, though authoring markdown in JSON is yucky. We could of course support more than one, like the_doc.jsonbut then try theREADME.mdif not present.