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.