Re: [Sbcl-devel] SBLC docstrings

[William H. N. <wil...@ai...>]

On Fri, Apr 14, 2006 at 10:13:49AM -0700, William Bland wrote:
> 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

We inherited a lot of the docstrings from text written for CMU CL back
when the earth was young, so in the absence of someone making it a
priority for a full time week or more of work (almost 1000 external
symbols, at 1 per 3 minutes?) they're not going to be uniformly
consistent with the modern world.
 
> 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 useful.

If we become convinced that the current level of inconsistency makes
the current partly-legacy docstrings a problem, something as drastic
as that might in fact be done. It might even be useful: many people
program with a magical environment which can be configured to bounce
to the CLHS page with a single click, and some of the rest (like me)
program with the CLHS symbols page open in their browser.

I doubt you're guessing correctly exactly what the drastic solution
would be: we need to have someplace in the system documentation for
non-CLHS extensions (e.g., :WEAK-FOO options for MAKE-HASH-TABLE), and
docstrings seem like a reasonable place, and deleting all the
docstrings would not serve. However, making most of the docstrings 
be CLHS URLs, and adding text after that for those symbols which need
non-ANSI behavior documented, might serve.

If I had implemented the system from scratch, at a time when
machine-readable standard documentation was available, something like
that is likely what I would have done. And, although my dislike for
manually maintained duplicate information is so strong that it makes
me an outlier in the programming community in general, among the
self-selected community of people who have looked at SBCL and chosen
to do a lot of work on it, I seem to be nearer the mainstream.:-|

> 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 am not sure that they would be better than
 >   CL-USER> (documentation '*print-case* 'variable)
 >   "See <ansiclhs://variable/star-print-case-star>."
or
 >   "See <ansiclhs://function/format>."
or
 >   "See <ansiclhs://function/read-char>."
and still less sure that they would be so much better that it will be
possible to make them happen. The volunteer labor of others is free,
but also its supply is nonetheless limited in various ways.

-- 
William Harold Newman <wil...@ai...>
PGP key fingerprint 85 CE 1C BA 79 8D 51 8C  B9 25 FB EE E0 C3 E5 7C
Ubi saeva indignatio ulterius cor lacerare nequit. -- Jonathan Swift's epitaph