Re: [Sbcl-devel] SBLC docstrings

[William B. <doc...@gm...>]

On 4/14/06, Christophe Rhodes <cs...@ca...> wrote:
>
> Sure.  There is an extremely good reference for standardized
> functionality, the hyperspec.  Providing additional documentation
> which adds nothing in a place that might be construed as being more
> accessible or more relevant is harmful to beginning users, because
> they might well treat the wrong source of data as authoritative.

OK, makes sense, thanks.

> > In case it helps to know my motivation for doing this, LispDoc runs on
> > SBCL and uses documentation strings as short descriptions of each
> > result, to display alongside links to things like the CLHS and PCL.
>
> That's a fine motivation in the abstract, but I'm afraid I can't see
> any good reason to do this.  Documentation strings for anything that
> isn't in the CL package aren't likely to be short, as they are (at
> least potentially) used in the manual as part of the paper
> documentation; you could argue that CL package symbols are a special
> case, and indeed that's also what I'm arguing: I would suggest that
> for your LispDoc application you use as a short description the first
> sentence or the first paragraph of the Description section of the CLHS
> entry.
>
> Maybe I'd want to know why you think that including documentation
> strings as short descriptions on CL symbols helps anyone who isn't a
> user of your application. :-)

OK, fair enough, let's forget LispDoc for now - I could clearly just
not rely on docstrings and get the short descriptions elsewhere.

But I'm still bothered by SBCL's docstrings for :CL symbols.  I guess
the main reason they bother me is that they're not consistent, and
that makes them less useful than they could be (both to human
consumers of docstrings, and to programs that use them).  Some symbols
have very short documentation:

  CL-USER> (documentation '*print-case* 'variable)
  "What case should the printer should use default?"

Others have rather long documentation:

  CL-USER> (documentation 'format 'function)
  "Provides various facilities for formatting output.
  CONTROL-STRING contains a string to be output, possibly with embedded
[snip - this is a long docstring... it even has examples of using format!]
  FORMAT has many additional capabilities not described here. Consult the
  manual for details."

Still others have no documentation:

  CL-USER> (documentation 'read-char 'function)
  NIL

I guess, reading a little into your reply, your view is that *none* of
the symbols in :CL should have docstrings (unless there is something
left undefined in the hyperspec, and the docstring is just a note
saying how things are done in SBCL).

That's certainly a consistent thing to do, but I'd argue it's not very usef=
ul.

Of course, putting the entire hyperspec entry into each docstring
wouldn't be very useful either, even if it was possible (as far as I
understand, the license would forbid it).

I'd argue that an alternative that is both consistent and useful, and
gets past your first objection (misleading the user as to the
authoritative place for documentation), would be to have a short
description for every symbol in :CL, always ending with some text like
"see the hyperspec for definitive documentation".

So the docstrings for the above symbols might be something like:

  CL-USER> (documentation '*print-case* 'variable)
  "Controls the output case for the printer.  Can be :upcase,
:downcase, or :capitalize.  See the hyperspec for definitive
documentation"

  CL-USER> (documentation 'format 'function)
  "Provides various facilities for formatting output to a stream or to
a string (if the first argument is NIL).  CONTROL-STRING contains a
string to be output, possibly with embedded directives, which are
flagged with the escape character \"~\".  Remaining arguments are
processed by those directives.  See the hyperspec for definitive
documentation"

  CL-USER> (documentation 'read-char 'function)
  "Reads and returns the next character from a stream.  See the
hyperspec for definitive documentation"

Why do I think these are useful even for people who aren't users of
LispDoc?  Well, they serve to remind the user of the most important
aspects of each symbol without making the user go read the entire
hyperspec entry.  The above docstring for *print-case* tells me
everything I would normally need to know about it in order to just go
ahead and use it.  I wouldn't ordinarily need to know all of the gory
details in the hyperspec (e.g. interactions with *print-escape*, etc).

I'm off on holiday tomorrow, for a week.  Probably won't have much
internet acess while I'm away, but I do look forward to talking more
about this when I get back.

Cheers,
Bill.
--
William Bland: http://www.abstractnonsense.org/
Lisp documentation: http://www.lispdoc.com/