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.