Subject: Re: So, where's the "Javadoc" for COMMON Lisp? From: Erik Naggum <erik@naggum.net> Date: Wed, 18 Jul 2001 18:09:43 GMT Newsgroups: comp.lang.lisp Message-ID: <3204468580853022@naggum.net> * Raymond Toy > I'm not familiar with javadoc, but perhaps Mark K's user_man package > is what you are looking for. (See the CMU AI archives). It extracts, > I think, the docstrings of functions and produces TeX output for the > function and docstring. I think this is a bad way to use documentation strings. This is also why I think literate programming is bunk. The best case of documentation strings put to real use that I know of is GNU Emacs. Even with Emacs, there is a separate manual, written to be _read_, that describes a lot more stuff in a pedagogical order and with an eye to physical proximity of related details and information. Documentation strings are somewhat like hypertext at its worst (i.e., not much better than the Web): They are intended to be read in a very well-defined context of pre-existing knowledge. Just like the argument list of a function should not be used to tell those who do not know what it does how to use it, documentation strings should not be considered the final word. Extracting them into an external file in randomized order (such as alphabetically by symbol name) is worse than useless -- a programmer who used them intelligently would arrive at them through a path of discovery that has no relation to simple collation orders. The more standardized something is, the more one must expect people to know it. A brief documentation string would not suffice for symbols in the common-lisp package, because anything that could be written briefly would already be known to the reader. The need for access to the full- blown documentation in a nicely formatted and consistent form arises from the fact that people will look for different minute details and should be able to end their search quickly because they are in known territory. Writing good documentation is hard, because intelligent people bore easily and just put down documentation that explains the obvious, yet do not use documentation that fails to be readable. What should be in the documentation is stuff that people cannot figure out for themselves faster than reading it. That is why I love specifications to be online and why I think hypertext in specifications is such a wonderful use of the technology. This is why I wrote hyperspec.el. But now I want the same level of documentation for vendor-supplied pacakges that come with tons of high quality documentation, although more of a tutorial kind than specifications, since it is written after the fact, rather than before. The reason I think literate programming is so stupid is the same reason I found SGML's promise of "one source, multiple publications" to be so hollow and ignorant. A piece of text has an audience, a context, and a set of expectations associated with it. Until we can program computers to deal with this, _people_ need to write text for different audiences, different contexts, and different expectations. When I look at code, I expect the documentation there to help me understand it. When I read the documentation, I hope to understand the system design. If the system design expectation is attempted filled by giving me a mere dump of the code documentation sans code, I have reason to accuse people of fraud. When I read specifications, I expect it to become the background noise of my own expectations when I deal with a conforming system. (This is why lack of conformance is so much more annoying than bugs in stuff that does nto purport to conform to a specification; I have to become _conscious_ of my expectation that the specification is actually implemented, and that means having to test for it and not being able to believe it. This is like asking people if they understand every word you use, instead of assuming that you agree to speaking the same language.) Also, please note that a lot more than functions have documentation. That often tends to be forgotten in systems that primarly have functions as exportable interface concepts. Classes, slots, types, packages, variables, and a lot more stuff have documentation in Common Lisp. It is sometimes hard to understand how people who invented these things could be so futuristic that they would foresee such needs. (It is likewise sad to see vendors completely ignoring the specification and reinventing the wheel badly when the "need" suddenly arises and half-assed stuff like the "web" suddenly appears.) #:Erik -- There is nothing in this message that under normal circumstances should cause Barry Margolin to announce his moral superiority over others, but one never knows how he needs to behave to maintain his belief in it.