JavaScript Self-documenting code where's the API Docs tools?

Question

These two concepts seem counter-intuitive. There's one side of the argument that sees the harm that comments do to readability, and violations of DRY (if the comments are even kept up to date). However, flip the coin and there is a necessity to provide good API documentation for your code so others can use your libraries.

Every tool (JSDoc, PDoc, etc.) I have seen that is designed for generating API docs uses an extreme amount of space to provide that documentation. I need to provide API documentation, what I don't need is to have half of my LOC be specially formatted commenting so JSDoc can read it.

I'm currently considering a basic markdown tool like Jekyll and putting this documentation in a /doc folder, totally removing it from my code. Has anyone else found an approach to this problem that has worked for them?

Answer 1

Sphinx is a documentation tool for many languages, which assumes that you will write your documentation mostly in external files. Still it has an autodoc extension which allows you to extract documentation from the comments in the code.

I personally find it more convenient to have the API documentation just near the code, as it helps me keeping it up to date. Moreover, other people working on that code will be able to have the documentation just when they need it, without having to browse external files. I frankly do not see anything wrong in having most lines of code which are comments: editors usually color comments differently and allow you to ignore them if you want.