Docstring conventions ?

In Emacs Lisp, there's a convention that the first line of a
function's docstring should be a concise sentence providing a general
description (some of the interactive help mechanism assumes that).

Are there any conventions or style recommendations for Common Lisp
docstrings?

--
Resistance is futile. You will be jazzimilated.

Scientific site: http://www.lrde.epita.fr/~didier
Music (Jazz) site: http://www.didierverna.com

EPITA/LRDE, 14-16 rue Voltaire, 94276 Le Kremlin-Bicêtre, France
Tel. +33 (0)1 44 08 01 85 Fax. +33 (0)1 53 14 59 22

På Tue, 19 Aug 2008 17:42:31 +0200, skrev Didier Verna
<didier@lrde.epita.fr>:

> In Emacs Lisp, there's a convention that the first line of a
> function's docstring should be a concise sentence providing a general
> description (some of the interactive help mechanism assumes that).
>
> Are there any conventions or style recommendations for Common Lisp
> docstrings?
>

There is no simular convention in CL.
Peder Norvigs luv-slides http://norvig.com/luv-slides.ps page 90 describes
commenting and docstrings.
Lisp documentation generation systems like Tinaa have their own
conventions.

--------------
John Thingstad

"John Thingstad" <jpthing@online.no> wrote:

> There is no simular convention in CL. Peder Norvigs luv-slides
> http://norvig.com/luv-slides.ps page 90 describes commenting and
> docstrings. Lisp documentation generation systems like Tinaa have
> their own conventions.

Thanks.

--
Resistance is futile. You will be jazzimilated.

Scientific site: http://www.lrde.epita.fr/~didier
Music (Jazz) site: http://www.didierverna.com

EPITA/LRDE, 14-16 rue Voltaire, 94276 Le Kremlin-Bicêtre, France
Tel. +33 (0)1 44 08 01 85 Fax. +33 (0)1 53 14 59 22

In article <muxmyj9au54.fsf@uzeb.lrde.epita.fr>,
Didier Verna <didier@lrde.epita.fr> wrote:

> In Emacs Lisp, there's a convention that the first line of a
> function's docstring should be a concise sentence providing a general
> description (some of the interactive help mechanism assumes that).
>
> Are there any conventions or style recommendations for Common Lisp
> docstrings?

Most recommendations are either general (see Pitman/Norvig
Tutorial on Good Lisp Programming Style) or very specific
(used by systems who add some kind of syntax to documentation
strings).

The first thing to do is to make the parameter list
as speaking as possible.

(defun foo (&rest args) ...)

Above is bad, since 'args' does not give much of a clue.
Common Lisp has keyword arguments with defaults.

(defun draw (object &key style stream) ...)

Since there is no good place to describe and retrieve
the types for the arguments one might want to
use a) methods to specify the classes (when possible)
or b) describe the argument types in the documentation
string.

Next are return values. Good idea to describe those
in the docstring.


Then a description what the function actually computes.

Then side-effects.


The main purpose for documentation strings is a)
interactive lookup and b) documentation generation.

The developer using a Lisp system sees some symbol
in the code or she looks up some symbol by name
and wants to get an idea what the function does.
For me the interactive lookup is important.

Unfortunately some IDEs aren't that good showing
the docstring. LispWorks uses m-c-sh-a to show
arglist and docstring.

--
http://lispm.dyndns.org/

On Aug 19, 1:00*pm, "John Thingstad" <jpth...@online.no> wrote:
> På Tue, 19 Aug 2008 17:42:31 +0200, skrev Didier Verna *
> <did...@lrde.epita.fr>:
>
> > * * * *In Emacs Lisp, there's a convention that the first line of a
> > function's docstring should be a concise sentence providing a general
> > description (some of the interactive help mechanism assumes that).
>
> > Are there any conventions or style recommendations for Common Lisp
> > docstrings?
>
> There is no simular convention in CL.
> Peder Norvigs luv-slideshttp://norvig.com/luv-slides.pspage 90 describes *
> commenting and docstrings.
> Lisp documentation generation systems like Tinaa have their own *
> conventions.
>

I do use Emacs-style conventions in CL code as well (plus the < 80
column limit). The rest is tricky and tool-dependent, but I would
really suggest following the "first line summary" style as much as
possible.

Cheers
--
Marco

Marco Antoniotti wrote:

> I do use Emacs-style conventions in CL code as well (plus the < 80
> column limit). The rest is tricky and tool-dependent, but I would
> really suggest following the "first line summary" style as much as
> possible.

Yup; that's what I do all the time unconsciously. And then I suddenly
figured, "but this is not Elisp", so I asked.

--
Resistance is futile. You will be jazzimilated.

Scientific site: http://www.lrde.epita.fr/~didier
Music (Jazz) site: http://www.didierverna.com

EPITA/LRDE, 14-16 rue Voltaire, 94276 Le Kremlin-Bicêtre, France
Tel. +33 (0)1 44 08 01 85 Fax. +33 (0)1 53 14 59 22