Subject: Re: So, where's the "Javadoc" for COMMON Lisp?
From: Erik Naggum <erik@naggum.net>
Date: Wed, 18 Jul 2001 15:41:51 GMT
Newsgroups: comp.lang.lisp
Message-ID: <3204459709990624@naggum.net>

* Kent M Pitman
> (Why just those and not even user-defined symbols?)

  Primarily because they would be in "sealed" packages with their external
  specification and documentation, anyway.  It would be a waste to keep a
  watered-down version in documentation strings.

* Marco Antoniotti <marcoxa@cs.nyu.edu>
> However, I would not discard the idea of a Document Generator.  I like to
> have "clean" doc strings in lieu of comments.

  I think there is something to be said for a low-cost documentation like a
  simple string.  As I expect more from the specification in the HyperSpec
  and I expect more from vendor documentation, I expect that documentation
  for code in development _not_ be polished and indexed and everything web
  pages, but rather something that is so easy to write well and maintain at
  a high quality that it does not seem like the drag that documentation so
  often is considered to be.  I also personally prefer to leave the quality
  publication job to people who are good at it, instead of me trying to to
  something I both dislike and feel inept at.  One of the reasons I do not
  write a lot of web pages is that I have tremendous respect for typography
  and nearly everything I do with that abominable HTML thing really sucks
  -- much less than most of what is out there on the "web", but it still
  looks mostly awful and screams incompetence.  Although not only and not
  necessarily mine, I still get blamed for how it looks.  I would much
  rather publish something in PDF than that hot toy markup language.

#: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.