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!
Top comments (0)