Feature Request: "self documenting code" based on JSDoc Support

[timoc]

One of the issues i have using modules and libraries with jsish, is that the documentation and help system, while broad, is not deep. It is also not clear how to extend the help to cover my own code. Often i have to read source in this jsish repo to get an idea of what is available and how to use it.

The self documenting concept/idea is to integrate a tool like jsdoc2md, as part of the integrated help system. The self documenting use case would extend jsish help to scan the available jsi source, (in local, vfs etc.) to build a reference manual based on available code. A jsdoc capability could also be used to dynamically document jsdoc supported external components like Vue.js. If not dynamically, then including static jsdoc to markdown step in the build step can be used to generate the Vue.js documentation for \lib\www\md. from unminified js source. JSDoc is based on /** .... *\ C style comments, so could also generate API docs from the C source.

In principle jsdoc information could also be used to improve/extend es5lint. That is, to compare jsdoc api documentation with api implementation, something like the es5lint-plugin-jsdoc.

[pcmacdon]

A great idea. Except jsdoc2md is written in nodejs, so there is no way to "integrate" it, per-se.

Most self documenting code systems focus on documenting individual functions, whereas Jsi documents at the module level.

The "help" command in jsish relys on Info.cmds() to access information about builtin commands.
It can also dump help for modules (eg. help Websrv).

But I noticed a bug in interactive jsish where help pdq does not work when in the 'pdq' directory. (just committed a fix).
However jsish . -h does.

The docs in Jsi could definitely stand improvement, but I'm not sure how at this point.

[timoc]

If you consider it a reasonable idea, then i think there are integration options, depending on the capabilities you want.

To my mind, a JSI "self documenting support" development roadmap might be something like:

• Extend the JSI parser and add options to scan/parse a file and print any C style comments it finds to stdout. Add this to the CLI as a non MD CLI self documenting support option.
• Create a JSI module like jsdoc-parse (or a jsi port of that library), to process C style comments, pick out the jsdoc formatted comments and create MD from them. Add a build step to use it on the C & Javascript sources to create/update static documentation. Add this as a jsish CLI command able to scan local and vfs sources.
• Extend the JSI parser to contain a JSDoc subset AST. Use the JSDoc AST to validate the JSI code AST against the JSdoc AST. Use it to generate JSI markdown, and/or spit out jsdoc templated JSI code from JSI source.
• Use the AST to link/extend the jsdoc @example tag to perform unit-testing and include the unit tests in the module documentation. This feature could also be separate. More often than not, the best examples and documentation on the API have been the unit tests.

Another option to "integrate" jsdoc2md could be to create a transpile pipeline from node to JSI as a make step. I have tested the transpile approach to get node code to run on non v8 engines with some success. This approach would use tools like browserify and Babel, to automate module/library conversion from node source to JSI source.
It might require an extra node API JSI wrapper to map File IO etc, but theoretically, you should then be able to add jsdoc2md as a an externally supplied module like vue.js. If you want to get meta, you could potentially transpile the node transpile pipeline into a JSI module :).

[pcmacdon]

I think the only viable option above is jsdoc-parse, because the jsi parser does not see comments as they get stripped. You might try porting that.

[timoc]

Thanks. As you may have guessed, have no time to work on this, so may pick it up later.