Subject: Re: (:documentation ...) form
From: rpw3@rpw3.org (Rob Warnock)
Date: Sun, 25 Jul 2004 20:18:53 -0500
Newsgroups: comp.lang.lisp
Message-ID: <p7WdnX1XqKNgxpncRVn-qw@speakeasy.net>
Rahul Jain  <rjain@nyct.net> wrote:
+---------------
| nikodemus@random-state.net writes:
| > Andreas Scholta <ascholta@t-online.de> wrote:
| >> Pascal Costanza <costanza@web.de> writes:
| >>> string. AFAIK, only defclass and defgeneric require the use of an
| >>> explicit :documentation option.
| >
| >> What about defpackage?
| >
| > And define-condition.
| 
| How about "any defining form that does not contain an essential (as in
| 'the essence of') code body"?
+---------------

I think you need to narrow that even further: "Any defining form
that does not result in a definition of a function or macro." (Or if
you're including all types of documentation, add compiler-macro and
method-combination.)

The term you were thinking of was probably "implicit PROGN" (or "implicit
BLOCK NIL", or even "implicit TAGBODY" in some cases, e.g., DOTIMES),
which would have been correct if talking about places where declarations
can occur. But from my reading of CLHS "Glossary: documentation string"
and "Standard Generic Function DOCUMENTATION", such an implicit
PROGN/BLOCK/TAGBODY body is not not, by itself, enough. To allow a
doc string, the implicit body must be in a function-defining context
(including DEFMACRO & LAMBDA).

-Rob

p.s. Hmmm... Even though CLHS "Symbol LAMBDA" says:

    Documentation is attached to the denoted function (if any is
    actually created) as a documentation string.

it seems that neither CMUCL-18e nor CMUCL-19a-pre3 support doc strings
in LAMBDA:

    > (lambda (x) "A doc string." (1+ x))

    #<Interpreted Function (LAMBDA (X) "A doc string." (1+ X)) {48044099}>
    > (documentation * 'function)

    NIL
    > 

Compiling doesn't help, either:

    > (compile nil (lambda (x) "A doc string." (1+ x)))
    ; Compiling LAMBDA (X): 
    ; Compiling Top-Level Form: 

    #<Function "LAMBDA (X)" {488F27F9}>
    NIL
    NIL
    > (documentation * 'function)

    NIL
    > 

CLISP-2.29 is even worse: it doesn't even allow function objects at all
(as opposed to symbols) as the first arg of DOCUMENTATION!!

    > (compile nil (lambda (x) "A doc string." (1+ x)))
    #<COMPILED-CLOSURE NIL> ;
    NIL ;
    NIL
    > (documentation * 'function)

    *** - DOCUMENTATION: first argument #<COMPILED-CLOSURE NIL> is illegal, not a symbol
    1. Break [6]> 


-----
Rob Warnock			<rpw3@rpw3.org>
627 26th Avenue			<URL:http://rpw3.org/>
San Mateo, CA 94403		(650)572-2607