API Documentation

[EternalDeiwos]

We need to discuss ways for us to publish documentation of our libraries. Currently how we have been doing this is by commenting our code in the jsdoc standard syntax and generating API documentation from it. Such API documentation should be available at https://anvilresearch.github.io/examplelib (published via gh-pages branch).

Things that we need to make this work would probably be something like a standardised, branded template design for the documentation pages and a root website (https://anvilresearch.github.io) with links to all of the other documentation pages.

[EternalDeiwos]

So one of the things that I found making up the example in the JWK repo is that it it's really inconvenient to duplicate (and potentially update) API documentation appearing in the code and in the README...

Is there anyway to automate this? Suggestions?

[christiansmith]

I wonder if there's a way to generate something like an API summary from jsdoc?

[christiansmith]

A few general observations:

1. I like jsdoc itself for this. The default template though is lacking in negative space and it's hard to parse visually. We need some design help to really make the content pop.

2. The consistency between docs and code with generated docs is fantastic. But javadocs/jsdocs (for example) are often confusing in their monotony. Having a paragraph or more of description per method helps a great deal. Can we establish some kind of guidelines, like "how to write a good method description"? Possibly something that could be included with comment snippet in editors.

3. Related to 2, inline examples are relevant and useful content to include. There's the @example tag. Should we consider always including at least one usage example?

4. I noticed looking at the docs on the phone that long lines in the example code overflow very quickly. I didn't count, but it seems like less than 80 chars. It might be good as a rule of thumb to break objects properties/array items onto separate lines, declare variables to reference specific props outside of function calls, etc.