Generating Documentation with JSDoc or Documentation.js or the like

[jmbothe]

Title says it all. Anyone have any thoughts on this topic?

For those not familiar with these tools, here is a very basic description: For every entry point in our API, we write a comment with a specific syntax directly above the block of code. The documentation tool parses the comment and outputs documentation for the block of code.

• JSDoc
• Documentation.js

[jhowardjr]

Should we create issues for documenting each existing function?

[jmbothe]

At this point I think the library is small enough that it could probably be a job for one or two people to setup the tool, and then to go through and describe the function and document the I/O. I'd be happy to be one of those people.

If we decide we want to auto-generate docs, then moving forward it would be a good idea to require future submissions to be documented at the time of PR.

Do any of you have a preference for one of the two tools above? Or something else? JSDoc is the most popular, but I think Documentation.js looks nifty.

[jhowardjr]

Let’s try documentation.js

[jmbothe]

@jhowardjr ok cool. I am messing around with it on another project now, so once I have a better idea of how to integrate it into this project, I'll get started on setting it up.

[jmbothe]

Here is a markdown file for an API for another project I am working on. Using documentation.js, there is no way to modify the theme/structure of the document. So, what you see is similar to what we will get if we choose this route. Let me know if it looks like an acceptable layout to you. thanks!

[jhowardjr]

Nice! I like it. On a side note here's a good ds and algo book that was used in a course on coursera https://leanpub.com/algo.

[jhowardjr]

#62 adds documentation.