documentation strings

[Kent M Pitman <KMP @ MIT-MC>]

    Date: Fri, 31 Aug 84 16:47 EDT
    From: "David A. Moon" <Moon@SCRC-STONY-BROOK.ARPA>

    Macros may expand into declarations.  May macros expand into
    documentation strings?

I remember discussing this. I don't remember if there was an outcome
and couldn't find it in Mary Poppins.

The problem is that declarations identify themselves by the car of the
form. Documentation strings don't. Hence,

(DEFMACRO FOO () "Foo")

(DEFUN BAR () (FOO) "Bar")

is clear enough, but:

(DEFMACRO DEFFROB (NAME &REST BODY) 
  `(DEFUN ,(SYMBOLCONC NAME '-FROB) () ,@BODY))

(DEFFROB FOO (FOO))

might be confusing in that a bogus documentation string might be
generated (assume the user doesn't know the implementation of either
FOO or DEFFROB). If you think it's unambiguous because (FOO) is in a
for-value situation, consider the conscientious macro-writer who knew
that the return value of frob functions were always ignored, so had
written instead:

(DEFMACRO DEFFROB (NAME &REST BODY) 
  `(DEFUN ,(SYMBOLCONC NAME '-FROB) () ,@BODY NIL))

to emphasize the fact. I find it distasteful to think that he'd have
to write

(DEFMACRO DEFFROB (NAME &REST BODY) 
  `(DEFUN ,(SYMBOLCONC NAME '-FROB) () NIL ,@BODY NIL))

to be safe. Unfortunately, this would mean (FOO) could not expand into
a declaration, which might have been desirable. His only alternative
is to write code to check the first n forms in BODY for 
declarations/doc-strings, which is something of a pain to be doing
everywhere.

The only happy way around it is to require documentation strings to be
visually apparent. I would support a move to allow a new declaration type
called DOCUMENTATION such that a macro wanting to provide documentation
could expand to (DECLARE (DOCUMENTATION "...")), which would not be 
ambiguous in the way that "..." at toplevel would be. A doc-string at 
toplevel could be magic shorthand for this declaration.

-kmp