Keene's Object-Oriented Programming in Common Lisp book uses the
(:documentation ...) form for defgeneric defclass, and perhaps other
places. Is this an obsolete means of just using a docstring? Or is
this something that is still done?
--
An ideal world is left as an excercise to the reader.
--- Paul Graham, On Lisp 8.1
David Steuber wrote:
> Keene's Object-Oriented Programming in Common Lisp book uses the
> (:documentation ...) form for defgeneric defclass, and perhaps other
> places. Is this an obsolete means of just using a docstring? Or is
> this something that is still done?
It's still done. In fact, defgeneric doesn't allow the use of "just" a
documentation string. The :documentation option must be used instead to
give the documentation string.
It depends on the def* macro how to declare the documentation string.
AFAIK, only defclass and defgeneric require the use of an explicit
:documentation option.
Pascal
--
Pascal Costanza University of Bonn
···············@web.de Institute of Computer Science III
http://www.pascalcostanza.de R�merstr. 164, D-53117 Bonn (Germany)
Pascal Costanza <········@web.de> writes:
> It depends on the def* macro how to declare the documentation
> string. AFAIK, only defclass and defgeneric require the use of an
> explicit :documentation option.
What about defpackage?
--
cheers,
Andreas Scholta
Andreas Scholta <········@t-online.de> wrote:
> Pascal Costanza <········@web.de> writes:
>> string. AFAIK, only defclass and defgeneric require the use of an
>> explicit :documentation option.
> What about defpackage?
And define-condition.
Cheers,
-- Nikodemus "Not as clumsy or random as a C++ or Java.
An elegant weapon for a more civilized time."
·········@random-state.net writes:
> Andreas Scholta <········@t-online.de> wrote:
>
>> Pascal 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"?
--
Rahul Jain
·····@nyct.net
Professional Software Developer, Amateur Quantum Mechanicist
Rahul Jain <·····@nyct.net> wrote:
+---------------
| ·········@random-state.net writes:
| > Andreas Scholta <········@t-online.de> wrote:
| >> Pascal 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.org>
627 26th Avenue <URL:http://rpw3.org/>
San Mateo, CA 94403 (650)572-2607
····@rpw3.org (Rob Warnock) writes:
> Rahul Jain <·····@nyct.net> wrote:
> +---------------
> | 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.)
<rolls up sleeves> All right.
A generic-function results in the definition of a function. However, it
uses a :documentation parameter.
Compiler-macros and method-combinations do have an essential code body,
so they have unadorned docstrings... Except for short form
method-combinations, which have a :documentation parameter. :)
> 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.
No, I was thinking of defining forms. If nothing is being defined,
there's nothing to document, as all there is is code that will be
executed at eval, load, and/or compile time.
> 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).
Yes, that's why I said "defining form". :)
I think my real purpose in generalizing the statement was so that people
creating their own defining operators would have some way of knowing
what syntax they should have for docstrings. That and my scientific bent
for trying to simplify complex rules with many cases into rules that
identify some more universal properties and behaviors. :)
> 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:
[...]
> 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!!
Nice catch! SBCL 0.8.12 has the same behavior as CMUCL.
--
Rahul Jain
·····@nyct.net
Professional Software Developer, Amateur Quantum Mechanicist
Andreas Scholta wrote:
> Pascal Costanza <········@web.de> writes:
>
>>It depends on the def* macro how to declare the documentation
>>string. AFAIK, only defclass and defgeneric require the use of an
>>explicit :documentation option.
>
> What about defpackage?
Ah right, and then also define-condition, and probably others as well.
Pascal
--
Tyler: "How's that working out for you?"
Jack: "Great."
Tyler: "Keep it up, then."