Re: Documentation strings and function.

[Christopher Fry <cfry@OZ.AI.MIT.EDU>]

Expressing the current CL syntax is complicated because the syntax is unnecessarily flexible.
Let's decide on whether the first doc string should be before or after the declarations
and change the spec to reflect that.

    I think multiple document strings should be allowed.  Perhaps all should
    precede any declarations.  The argument for multiple document strings is
    that one can then use a simple parsing program to collect documentation
    from code.  One could imagine a convention of the first document string
    describing the external interface or purpose of a document, and the
    second information about the implementation.  Why isn't the syntax

    ... lambda-list {documentation}* {declarations}* ...
I've yanked in Bobrow's statement since I think he has basically the right idea.
Here's an example of the format that I use:
(defun foo (a b) "this is THE doc string. It's used for describing the functionality of
   this function as seen by the outside world."
   (declare ...)
   (declare ...)
   (some code)
   "this is a programmer comment. I use it to say things like,
     FIX UP this code someday, or this algorhythm is too slow."
   (some code)
   "maybe another programmer comment"
   (final code))

The function DOCUMENTTION returns the top doc string.
My own function PROGRAMMER-COMMENTS returns a list of
strings. In the above example it would return the 2nd and 3rd strings
in the body. The programmer-comments above don't violate existing CL semantics.
And a clever compiler will just throw them out.

The restriction on programmer-comments is that they do not include the
first string in the body and do not include the last form in the body if that happens 
to be a string. The flexibility of whether doc strings or declarations go first
or intermingle is unncessarily confusing for both human and machine.

I find being able to imbed programer-comments in a definition and have a program that
can find them helps me make notes to myself in code. Frequently you know something is 
not working well but can't fix it at the moment. Having a convenient way to store
the information which a machine can get at and tell you about it when you ask 
is a great reminder.