Udoc is the name of my latest program to do literate programming, and I'm reusing it here, for writing about the subject. It is perhaps not a very good name, but I used it since the subject is such a many-faceted one:
API documentation is what I did at Trolltech. At least that's what I thought I was doing at the start. As I was developing the format and writing text, I found I could use the documentation for two other purposes:
Writing better code through writing documentation and thereby developing a better understanding.
Checking boxes is what I see much too often.
Be Documentation, or
I Will Document My Code; but the
actual documentation is meaningless — doesn't answer any
questions I have about the code or interface.
Literate programming tools can be used for all three. Some are better suited to one purpose, some to another. Disciplined usage can help reach a goal even if the program fails to help — I still think it's a failure, though.