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…
So I decided to take my work back underground 
Obviously I know I can just read the source, or even download the application that this library is part of, Liquidsoap, and see what it does. But that just reinforces my point: automatically generated documentation is clever, but it’s just not useful…
Like I say, I don’t mean to single these guys out, they’re giving away their work for free, after all. The problem is that everyone is using doc generators theses days, it’s the “done thing” and I don’t think anyone’s thinking about why.
Hey, good post! I’m from the Savonet team, and I won’t try to argue: our doc isn’t good, even for an ocamldoc-generated doc. I’m mostly involved in the core of liquidsoap, and for that part what you say is really true: documenting single functions doesn’t explain anything, only the big picture helps, i.e., describing the concepts involved, the sequence of method calls during streaming, etc. Note that it’s possible to give such information, or code examples, within ocamldoc’s framework. But the point remains: ocamldoc often serves as an excuse.
By the way, liquidsoap uses dtools but overrides its syntax for configuration. So even I do not remember the regular dtools’ configuration syntax.
😀
I do fully appreciate the effort people put in to develop code and make it available for others at no charge, if I get the time I will try to figure it out and post it here, for my next project I fear I’ll have to use shudder XML…
Hello there! I will try to commit some documentation in dtools soon, if it is not too late for you 🙂
Merci m’sieur! 😀
Wait, if the syntax is enough for you to use dtools instead of XML, I extracted it for the good of you and dtools: it’d be nice that not all of our libraries are solely used by liq :p
Files have one definition per line, and lines starting with # are comments. Definitions are of the form TYPE KEY : VALUE where TYPE is unit, int, float, bool or list, KEY is the name of the setting and VALUE is the value, whose syntax is as in OCaml (3.14 is a value of type float) except for (string) lists which are written e.g. foo:bar.
Now appart from that, you can look at liquidsoap for how to define settings, setup loggers and run stuff…
Merci beaucoup! 🙂
In fact just today I had a colleague at my desk asking about some code I’d written ~3 years ago, documented only in Pydoc… Took me a while to wrap my own head around it again, no wonder he was stuck on it!