Using 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!