PARSE-BODY

[Kent M Pitman <KMP@STONY-BROOK.SCRC.Symbolics.COM>]

    Date: Sat, 27 May 89 15:50:44 PDT
    From: Jon L White <jonl@lucid.com>

    ... Lucid implemented PARSE-BODY exactly according to Steele's description;
    but apparently not enough other implementations did so. ...

I don't recall Steele's description. Cloe implements a function named PARSE-BODY
internally which may or may not be related:
 (PARSE-BODY body env) => forms, decls, docs
All three return values are lists (for convenience with ",@"), but the `docs'
value never contains more than one string.

There is a discrepancy between the formal syntax description of DEFUN and 
LAMBDA on p67 and the text that follows two paragraphs below. The paragraph
which begins with "If the optional..." ends with "It is an errro if more than
one doc-string is present." I have always (since I noticed it, anyway :-)
taken the text to have priority over the syntax description. My guess is that
Mr. Duff didn't notice the text override.

Cloe's PARSE-BODY (used in implementing New Flavors, for example) signals the
error, though not for any highly principled reason.

Btw, the correct way for Steele to have written the syntax to avoid this
confusion would presumably have been:

 lambda lambda-list {declaration}* [doc-string] {declaration}* {form}*

-- though it looks fairly yucky. Probably better would have been to strike
the one-doc-string restriction and just permit multiple doc strings. That
way, people could write:

 (defun foo ()
   "This is a very long doc string"
   "that didn't fit all one one line."
   ...)

I certainly believe that would be more aesthetic than:

(defun foo ()
   "This is a very long doc string
    that didn't fit all one one line"
   ...)

or:

(defun foo ()
   "This is a very long doc string
that didn't fit all one one line"
   ...)

As I recall, this was discussed explicitly in the production of CLtL. The
main issue was what DOCUMENTATION would produce in the case of multiple
doc strings. My preference was then (and is now) to have DOCUMENTATION do
 (FORMAT NIL "~{~A~â??~%~}" strings)
in order to support multiple doc strings as a solution to the `indentation
problem' cited above.

Summary:

 - I'm fairly agnostic about whether PARSE-BODY should be there.  It's less
   needed now that there is no macro expansion to contend with, but the idiom
   of extracting DECLARE expressions from the top of a body is still needed
   even so, and this does help to do that concisely, so my personal inclination
   toward the feature would probably be mildly positive.

 - I don't think there is an ambiguity about doc strings, but I do think the
   restriction is gratuitous and would not oppose its removal.  This would
   simplify the syntax description and admit a programming style that some
   would find useful. Clarifications of how DOCUMENTATION and PARSE-BODY
   treated the situation would be in order.