2

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?

Drew
  • 4,683
  • 4
  • 35
  • 50
  • 3
    If you use a compression script at build time, you really do not have to worry about the extra lines in your code. – epascarello Mar 17 '11 at 18:03
  • 2
    Full ack. If you want to provide good quality documentation it should stay with the source code. When using a compressed file in production (which you should do anyway) the comments don't matter at all. – Daff Mar 17 '11 at 18:09
  • 1
    Not worried about the production files, compressors will remove it. I want readable files that aren't 75% specially formated comments just so some tool can read it. – Drew Mar 21 '11 at 18:33
  • 1
    I can't upvote this question enough. Seems like all of the JS documentation tools don't do anything useful without specially-formatted comments. And I agree w/ the OP, I don't want to junk up my source with rotting comments. Is the dynamic nature of JavaScript just too difficult for such tools to deal with? – Allan Feb 06 '14 at 23:07

1 Answers1

0

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.

Andrea
  • 20,253
  • 23
  • 114
  • 183
  • This looks pretty cool as far as using external files. I'd like to stick to markdown for cross-tool complain though, since a lot of people are switching to markdown. Can this parse JavaScript files? – Drew Mar 21 '11 at 18:32
  • I haven't tried it, but autodoc should work with Javascript files as well. – Andrea Mar 21 '11 at 19:46