Re: [Sbcl-devel] SBLC docstrings

[Christophe R. <cs...@ca...>]

"William Bland" <doc...@gm...> writes:

> I can certainly understand and agree with the first part of the above;
> the documentation is not strictly necessary since you can look it up
> in other places.  The second part seems to suggest that you're making
> the leap somehow from "not necessary" to "actively harmful".  Could
> you expand on this a little?

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.

> 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. :-)

Cheers,

Christophe

(Again, I want to reiterate: if the documentation string actually adds
to the information, say by mentioning a workaround for something, some
connection with some other operator, or similar, then that is a fine
motivation for adding one.)