Perhaps it’s just me, but I think that Javadoc (and its descendents, including OCamldoc) have set the cause of proper documentation very far back. If you already know an API and just need a refresher on the details, great! Tho’ it is nothing a halfway decent IDE couldn’t do on the fly (or even
C-c C-t in Emacs). But if you are just getting started with an API then what you need is sample code. Microsoft have always understood this; MSDN is full of little snippets that don’t do very much by themselves, but show how things hang together. Oh right, I get the result from this, and from that, and give them to the next thing. That is one of the things I am doing, or trying to do, with this blog.
It’s a running joke that developers hate writing documentation, and in many cases there is a grain of truthiness in that. Automatic documentation generators allow us to tick the box that yes, there is documentation, even better industry best practice documentation. All you need to do is write a couple of sentences in the comments as you go along, which you would probably write anyway, it’s painless. But documentation isn’t for the manager who insists that you write it but will never, ever look at it himself. It’s for the next programmer, and to him it looks like a box full of puzzle pieces but no picture on the lid.
Not to single anyone out here, but what triggered this little tirade was
libdtools-ocaml-dev including OCamldoc but no example of what a configuration file actually looks like…