[JavaScript] Developer Documentation

[dignifiedquire]

After looking at the lovely new documentation of async I wanted to start a discussion on tooling and the way we can provide great documentation (preferably auto generated as much) to all the JavaScript projects.

The two main projects for generating api documentation from JavaScript are as far as I know currently

• JSDoc (used by async)
• ESDoc

[dignifiedquire]

cc @diasdavid @RichardLitt @haadcode

[victorb]

Just as an note, I always see documentation as three different things.

First we have the holy tutorial which is a introduction with some easy things to do with something.

Then we have the (API) documentation which is what I think is what you're talking about here. Basically lists the functions, theirs signatures, what it returns, some examples and other things.

Thirdly, we have guides which is like the tutorial, but assumes that the reader have done some reading from the API documentation + went through the tutorial.

As I was looking at async, I realized that there only seems to be an API documentation. Considering that this issue mentionts "Developer Documentation", we should really think about all three parts.

[dignifiedquire]

@victorbjelkholm I fully agree, the main thing I was thinking about when I wrote this was the automated part that's why I mentioned those tools and the documentation of async. The others two parts tutorial and guides rely much less on tooling and are much more a case of just write the thing.

[RichardLitt]

Regarding automatically making tool, all that I know of is jsdocs. However, I find this to not be ideal; it is very hard to get developers into the habit of using jsdocs, and I find that it makes the code seem bloated. I am in favor of other methods, such as Readme Driven Documentation. But I'm am agnostic as to how we doing this, with the only constraint being let's do what works, and iterate on it. I just like keeping the code and the docs separate.

[dignifiedquire]

I just like keeping the code and the docs separate.

I think this works for small projects but I see that it is not working for js-ipfs in its size and scope and don't believe it ever will tbh. I think to get people in the habit of documenting their code and enforcing it as much as possible by putting the documentation in the code is a much more realistic way to go for us.

[RichardLitt]

That's a fair point. I think if we modularize well - one package, one thing - we can do RDD, but otherwise, we may need to overload with a giant structure. I keep seeing the complaint that js-ipfs is too spread out and hard to navigate, so it may be worth simply working on our documentation about how we discover modules, though, to be honest.

[daviddias]

Keep the discussion and good ideas coming, we will make sure to push this when we get to js-ipfs Milestone 4. Thank you:)

[rjrotheryjr]

I realize an automated tool significantly helps with the documentation process. However, is there any chance of creating a team dedicated specifically to documenting projects e.g. [JavaScript] Developer documentation. Do we have the resources for such a team? I find often that the documentation part of building software or the likes thereof seems to be a secondary thought.Yet tutorials, API documentation and guides become essential publications that users seek to better understand the innovation with which they are working.

[harlantwood]

Once we get API docs where we want them, we could add a CI step to cheer check all methods for docs (3+ lines, 1+ example, whatever we want for a min bar). So build fails if docs fall behind. Could do this pre-push as well, in a hook or script.

[dignifiedquire]

This looks very interesting. http://documentation.js.org/

There is also the thought of using Flow or TypeScript to define signatures that can be used in docs rather than having jsdoc style syntax for it.

[dignifiedquire]

To expand on the earlier comment, documentation.js allows the use of Flow type definitions instead of jsdoc comments, e.g.

// Regular jsdoc
/**
 * This function adds one to its input.
 * @param {number} input any number
 * @returns {number} that number, plus one.
 */
function addOne(input) {
  return input + 1;
}

// flow type 

/**
 * This function adds one to its input.
 */
function addOne(input: number): number {
  return input + 1;
}

[dignifiedquire]

Really nice api docs: https://www.mapbox.com/mapbox-gl-js/api/ generated using documentation.js

[dignifiedquire]

I just discovered https://github.com/Kegsay/flow-jsdoc which allows us to write jsdoc, but transform those into flow types for the flow type checker to check. It's not feature complete but should be easy enough to hack on all things we need. This would give us the benefit of using a non obtrusive way of documentation (jsdoc) + type checking our code to improve code quality.

[daviddias]

@dignifiedquire that looks cool indeed!

How will we go to try the different options? Will you port some repos and generate some pages for the rest of the JS folks to try and experiment with?

[dignifiedquire]

Not sure yet. There are actually not that many options currently that seem to be viable given the tooling support.

The resulting documentation should be pretty similar no matter what we choose and will design a custom theme for us that fits into the ipfs.io homepage as the current themes for jsdoc and documenation.js are not overwhelmingly good.

[RichardLitt]

@dignifiedquire I could help you out by going through and documenting one of the repos in a fork, see how it looks?

[haadcode]

I did some tests with documentation.js and orbit-db, see the results here: https://github.com/haadcode/orbit-db/tree/documentation.js/docs. I'm not extremely happy with it: some of the jsdoc annotations don't work out of the box and I feel generally it's a little messy.

[dignifiedquire]

@haadcode any ideas what else we could do?

[haadcode]

@dignifiedquire I ended up writing the API docs and examples manually for Orbit and orbit-db's modules. That was quicker and yielded results I'm happy with. I don't expect drastic API changes in those modules, so for now I'm gonna stick with that and if there are API changes in code we just need to make sure those changes are documented.

At the moment I'm not convinced automating the documentation is worth the effort vs. writing them manually. If you expect plenty/big API changes, then perhaps it makes sense. If not, then I think automation doesn't bring that much value vs. the effort.

[dignifiedquire]

With the amount of modules that we have to document and ensure a high quality of documentation I don't feel comfortable with sth that is not automated. With jsdoc we have the ability to enforce documentation (through linting) and check on every PR on every module if there is a base level of documentation. I know this does not guarantee good docs but it raises the required base level. Writing good documentation is then something we can iterate and improve on as a community.

I've started documenting js-ipfs-api with jsdoc and using the theme from async to generate some samples from it. You can see the code here

• https://github.com/dignifiedquire/aegir/tree/docs
• https://github.com/ipfs/js-ipfs-api/tree/docs

Given the aegir branch there is a new command aegir-docs which generates the documentation into the docs folder.

Screenshot.

[dignifiedquire]

it seems for documenting callbacks documentation.js does a better job as you can see from the above screenshot.

[daviddias]

Now tracked on ipfs/js-ipfs#615