From: Kalle Olavi Niemitalo
Subject: keyword or parameter in docstring?
Date: 
Message-ID: <87zn2jycpw.fsf@Astalo.kon.iki.fi>
I have some code that goes essentially like this:

(defparameter *probability* 1
  "the probability of the situation being examined")

(defparameter *deck* (make-deck)
  "the deck being examined; may be missing some cards")

(defmacro for-each-card ((card-variable
                          &key ((:deck deck-variable) '*deck*))
                         &body body)
  "Execute BODY once for each card.
Each time:
  CARD-VARIABLE is bound to a card from DECK-VARIABLE.
  DECK-VARIABLE is bound to the remaining cards, in unspecified order.
  *PROBABILITY* is bound to a fraction of its previous value."
  ...)

The purpose of the last documentation string is to explain the
interface of the macro, and I think the keyword :DECK is more a
part of that interface than the parameter name DECK-VARIABLE is.
So should the docstring refer to the keyword instead?
From: Marco Antoniotti
Subject: Re: keyword or parameter in docstring?
Date: 
Message-ID: <uZXcd.19$u5.34924@typhoon.nyu.edu>
Yep.  Use :DECK in the docstring.  That is what is visible in the API.

BTW, isn't this a cute feature of CL.  I find myself using it a lot 
recently.

Cheers

Marco




Kalle Olavi Niemitalo wrote:
> I have some code that goes essentially like this:
> 
> (defparameter *probability* 1
>   "the probability of the situation being examined")
> 
> (defparameter *deck* (make-deck)
>   "the deck being examined; may be missing some cards")
> 
> (defmacro for-each-card ((card-variable
>                           &key ((:deck deck-variable) '*deck*))
>                          &body body)
>   "Execute BODY once for each card.
> Each time:
>   CARD-VARIABLE is bound to a card from DECK-VARIABLE.
>   DECK-VARIABLE is bound to the remaining cards, in unspecified order.
>   *PROBABILITY* is bound to a fraction of its previous value."
>   ...)
> 
> The purpose of the last documentation string is to explain the
> interface of the macro, and I think the keyword :DECK is more a
> part of that interface than the parameter name DECK-VARIABLE is.
> So should the docstring refer to the keyword instead?
From: Manuel Simoni
Subject: Re: keyword or parameter in docstring?
Date: 
Message-ID: <37707ed1.0410191031.62743488@posting.google.com>
Marco Antoniotti <·······@cs.nyu.edu> wrote in message news:<·················@typhoon.nyu.edu>...

> BTW, isn't this a cute feature of CL.  I find myself using it a lot 
> recently.

Yeah, I especially like 
(defvar *x* ...)
(defun foo (&key ((:x *x*) *x*)) 
  ...)
From: Pascal Costanza
Subject: Re: keyword or parameter in docstring?
Date: 
Message-ID: <cl1gna$h6a$3@newsreader2.netcologne.de>
Kalle Olavi Niemitalo wrote:
> I have some code that goes essentially like this:
> 
> (defparameter *probability* 1
>   "the probability of the situation being examined")
> 
> (defparameter *deck* (make-deck)
>   "the deck being examined; may be missing some cards")
> 
> (defmacro for-each-card ((card-variable
>                           &key ((:deck deck-variable) '*deck*))
>                          &body body)
>   "Execute BODY once for each card.
> Each time:
>   CARD-VARIABLE is bound to a card from DECK-VARIABLE.
>   DECK-VARIABLE is bound to the remaining cards, in unspecified order.
>   *PROBABILITY* is bound to a fraction of its previous value."
>   ...)
> 
> The purpose of the last documentation string is to explain the
> interface of the macro, and I think the keyword :DECK is more a
> part of that interface than the parameter name DECK-VARIABLE is.
> So should the docstring refer to the keyword instead?

Definitely.


Pascal

-- 
Tyler: "How's that working out for you?"
Jack: "Great."
Tyler: "Keep it up, then."
From: Vassil Nikolov
Subject: Re: keyword or parameter in docstring?
Date: 
Message-ID: <lzvfd75l5o.fsf@janus.vassil.nikolov.names>
Kalle Olavi Niemitalo <···@iki.fi> writes:

> I have some code that goes essentially like this:
>
> (defparameter *probability* 1
>   "the probability of the situation being examined")
>
> (defparameter *deck* (make-deck)
>   "the deck being examined; may be missing some cards")
>
> (defmacro for-each-card ((card-variable
>                           &key ((:deck deck-variable) '*deck*))
>                          &body body)
>   "Execute BODY once for each card.
> Each time:
>   CARD-VARIABLE is bound to a card from DECK-VARIABLE.
>   DECK-VARIABLE is bound to the remaining cards, in unspecified order.
>   *PROBABILITY* is bound to a fraction of its previous value."
>   ...)
>
> The purpose of the last documentation string is to explain the
> interface of the macro, and I think the keyword :DECK is more a
> part of that interface than the parameter name DECK-VARIABLE is.
> So should the docstring refer to the keyword instead?

  Hmmm, to say that ":DECK is bound to" something doesn't sound right,
  and in any case shouldn't macros be documented differently from
  functions, along the following lines:

    FOR-EACH-CARD (card-variable [ :DECK deck-variable ]) form*  [Macro]

    Execute the forms once for each card.
    Each time:
    * card-variable is bound to a card from the value of deck-variable;
    * deck-variable (if unsupplied, *DECK*) is bound to the remaining
      cards, in unspecified order;
    * *PROBABILITY* is bound to a fraction of its previous value;
    (card-variable and deck-variable must be symbols).

  I don't think it is appropriate to say that a macro has an
  interface---it has a syntax.

  ---Vassil.

-- 
Vassil Nikolov <········@poboxes.com>

Hollerith's Law of Docstrings: Everything can be summarized in 72 bytes.
From: Marco Antoniotti
Subject: Re: keyword or parameter in docstring?
Date: 
Message-ID: <u2bdd.21$u5.35415@typhoon.nyu.edu>
Hi


Vassil Nikolov wrote:

> Kalle Olavi Niemitalo <···@iki.fi> writes:
> 
> 
>>I have some code that goes essentially like this:
>>
>>(defparameter *probability* 1
>>  "the probability of the situation being examined")
>>
>>(defparameter *deck* (make-deck)
>>  "the deck being examined; may be missing some cards")
>>
>>(defmacro for-each-card ((card-variable
>>                          &key ((:deck deck-variable) '*deck*))
>>                         &body body)
>>  "Execute BODY once for each card.
>>Each time:
>>  CARD-VARIABLE is bound to a card from DECK-VARIABLE.
>>  DECK-VARIABLE is bound to the remaining cards, in unspecified order.
>>  *PROBABILITY* is bound to a fraction of its previous value."
>>  ...)
>>
>>The purpose of the last documentation string is to explain the
>>interface of the macro, and I think the keyword :DECK is more a
>>part of that interface than the parameter name DECK-VARIABLE is.
>>So should the docstring refer to the keyword instead?
> 
> 
>   Hmmm, to say that ":DECK is bound to" something doesn't sound right,
>   and in any case shouldn't macros be documented differently from
>   functions, along the following lines:
> 
>     FOR-EACH-CARD (card-variable [ :DECK deck-variable ]) form*  [Macro]
> 
>     Execute the forms once for each card.
>     Each time:
>     * card-variable is bound to a card from the value of deck-variable;
>     * deck-variable (if unsupplied, *DECK*) is bound to the remaining
>       cards, in unspecified order;
>     * *PROBABILITY* is bound to a fraction of its previous value;
>     (card-variable and deck-variable must be symbols).
> 
>   I don't think it is appropriate to say that a macro has an
>   interface---it has a syntax.

I'd say you are right,  but the documentation you propose seems 
ambiguous to me.  It looks to my like you need both :DECK and 
DECK-VARIABLE.  The issue is that the :DECK keyword is actually the 
interface.  You do not know what the internal name is (assuming this is 
actually in the doc string)

Cheers
--
Marco
comp.lang.lisp / 2004 / oct