JSDoc

Very cool little system of documentation. Similar to how rust can generate docs from comments in the codebase, jsdoc basically does the same thing. By documenting my code in a standard way I can generate pretty good documentation easily.

Also trying out jsdoc themes is easy. All you have to do is install a jsdoc theme and then run jsdoc with the path of the theme. I tried a few themes out and each one has something I like and something I don't. The one that I ended up coming down to was minami or clean-js-doc. The reason for clean-js-doc was that it has a little search bar which seems pretty useful. I often use the search bar on rust's documentation site so I think it would be useful in my documentation as well. However minami looks the best to me and I ended up going with it.

I'll probably take a stab at trying to get it have a search bar as well as I think that could be fun to hack in.

I'm surprised at how easy and straightforward it was to write out the documentation for all the various functions and then generate a site for it.

Below is a snippet from my pick-universe addon. The key things are that you specify the parameters, their types and a short description. You do this for the returns as well and voila, you have documentation.

/** Class for all the universe functions */
class Universe {
    /**
     * Create a Universe object.
     *
     * @param {string} hostname - Hostname or ip address for the universe server. 
     * @param {string} username - Username to use to log in.
     * @param {string} password - Password to use to log in.
     * @param {string} account - Account to log in to.
     */
    constructor(host, username, password, account) {
        this._uv = new _Universe.Universe(host, username, password, account);
    }

    /**
     * Call a cataloged subroutine.
     *
     * @param {string} subroutine - The name of the subroutine.
     * @param {...args} args - The arguments to be passed to the subroutine.
     * @return {array} The args are returned with their changes.
     * 
     */
    CallSubroutine(subroutine, ...args) {
        args.unshift(subroutine);
        return this._uv.CallSubroutine.apply(this._uv, args);
    }
}

Then you can build documentation by using jsdoc.

> jsdoc index.js README.md 

You can also install a theme and easily try it out.

> npm install --save-dev minami
> jsdoc index.js README.md -t node_modules/minami/

This will get you something like:

https://nivethan.dev/documentation/pick-universe/

Overall it's a pretty great piece of software and I would have never tried it out if i didn't take a stab at making my own library. Very cool!