Feature Request: "self documenting code" based on JSDoc Support about jsish HOT 4 OPEN

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.

from jsish.

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 :).

from jsish.

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.

from jsish.

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

from jsish.