Improve & Rethink Documentation

[DirkToewe]

One of the many amazing features of Python is the way it handles docstrings. Documentation is not just available as generated (HTML) documents. It is also available at runtime, e.g. by using the help function, not unlike the --help argument offered by most Linux command line tools.

The docstring functionality is one of the key features that I miss most in JS, which is why I've tried to emulate it by creating the documentation at runtime inside of a single help.js module. It seemed like a good idea at the time given the pros:

• No need to learn JSDoc and JSDoc's conventions
• Documentation was available at runtime
• Documentation was concentrated in a single place.

With increasing size of the ND4JS library, the downsides of this approach become more and more appearent:

• Creating structured, good looking docs without something like JSDocs is a lot of work
• Centralized documentation of increasing number of modules lacks clarity.

Which leads to this issue: The way of documentation needs to be rethought. The best solution is likely JSDoc. Maybe the jsdoc-api can be used to still generate runtime docstrings.