From: Camm Maguire
Subject: Are doc-strings deprecated?
Date: 
Message-ID: <543c8xj3eh.fsf@intech19.enhanced.com>
Greetings!  Just wanted to poll current opinion on the best way to do
documentation in CL.

Take care,
-- 
Camm Maguire			     			····@enhanced.com
==========================================================================
"The earth is but one country, and mankind its citizens."  --  Baha'u'llah

From: Rahul Jain
Subject: Re: Are doc-strings deprecated?
Date: 
Message-ID: <87u11dhk1o.fsf@nyct.net>
Camm Maguire <····@enhanced.com> writes:

> Greetings!  Just wanted to poll current opinion on the best way to do
> documentation in CL.

Docstrings are great. They're accessible introspectively and supported
by all kinds of tools. DefDoc.umentation will allow you to write
docstrings in DefDoc syntax and have them formatted to plain
72-char-wide text for the docstring. I think I'll also have some
features for automatically generating stuff like the arglist for display
in the documentation (marking some args as undocumented if the
documentation does not describe them). I think this will require
shadowing DEFUN. Bleh. Anyway...

-- 
Rahul Jain
·····@nyct.net
Professional Software Developer, Amateur Quantum Mechanicist
From: Alexander Schreiber
Subject: Re: Are doc-strings deprecated?
Date: 
Message-ID: <slrnc3skdk.8bs.als@thangorodrim.de>
Camm Maguire <····@enhanced.com> wrote:
>Greetings!  Just wanted to poll current opinion on the best way to do
>documentation in CL.

As one who spent more than 10 years with other languages (Shell, C,
Pascal, Perl, PHP, (pg)SQL, ...) I had developed the habit of putting a
few lines of documentation comments at the start of each
function/procedure - together with Perl scripts to extract this
documentation when needed. When starting with Lisp, I found the concept
of doc-strings as inline documentation (which is even available via
introspection - hey, great!) I _really_ nifty feature. And so I'm making
good use of it ;-)

So, I consider doc-strings not deprecated at all, rather, I strongly
support using them.

Regards,
       Alex.
-- 
"Opportunity is missed by most people because it is dressed in overalls and
 looks like work."                                      -- Thomas A. Edison
From: Nikodemus Siivola
Subject: Re: Are doc-strings deprecated?
Date: 
Message-ID: <633d72b.0402270201.7ff3b65b@posting.google.com>
Camm Maguire <····@enhanced.com> wrote in message news:<··············@intech19.enhanced.com>...
> Greetings!  Just wanted to poll current opinion on the best way to do
> documentation in CL.

There are different kinds of documentation, and many ways to slice the
cake.

Here's mine:

* User visible names (functions, arglists, etc) are the "minimum" API
description, and internal names are the "minimum" internal
documentation.

* Docstrings are good for shortish uasage and API-reminders, etc.
Something more verbose then the arglist, but much shorter then a real
spec (ala CLHS) would be. Overly long or marked-up docstrings can
obfuscate the source.

* Comments are good for documentation that deals with the
implementation, and esp. when such that really doesn't make sense
without seeing the source.

* Implementation manuals are good for outlining architectural
decisions, looking at the whole from a more removed POV.

* Reference manuals are good for accurate and extensive interface
specifications. Think CLHS.

* User Guides are good for ignoring details that don't matter 98% of
the time, and explaining the basics.

Trying to cram all of this variety into a single box sounds like a bad
idea to me.

Ob dreaming: in an ideal world I'd like to see a way of relating
all/most of this information in a running system: functions would know
about their respective manual entries, etc.

Cheers,

 -- Nikodemus Siivola