[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Portable way to get a function's arg list AND DOC STRING??

    Date: Tue, 24 Mar 1992 11:39 EST
    From: barmar@Think.COM (Barry Margolin)
    The DOCUMENTATION function works fine on Symbolics systems, except that
    most of the Symbolics-provided functions and variables don't have
    documentation strings. ...

Speaking less as a Symbolics employee and more as a member of X3J13 (the
ANSI CL subcomittee), here's a little extra information on the issue.
(Barmar's a member of the committee, too, and I'm sure knows it as well,
but just forgot to mention this stuff.)

No pre-defined function (not even a CLtL-defined function) is required
to have a documentation string.  (i.e., it is definitely not a bug or
non-conformance in Symbolics software that we don't provide them.)
Further, the working draft ANSI spec goes farther by adding explicit
wording that says:

 Documentation strings are made available for debugging purposes.
 Conforming programs are permitted to use documentation strings 
 when they are present, but should not depend for their correct
 behavior on the presence of those documentation strings.  An 
 implementation is permitted to discard documentation strings at
 any time for implementation-defined reasons.

I know this seems harsh given your desire to write portable
documentation tools, but the point is that doc strings are really an
"environment" issue, not a "linguistic" issue.  To require them to be
maintained would be to require implementations to be bloated with
information that might not be appropriate to the user interface style of
the implementation in question-- either because it has an alternate
documentation mechanism (e.g., in Genera) or because it has aspirations
of fitting in some very small number of megabytes (which I believe was
X3J13's primary motivation in adding the above-cited paragraph).

Note that the situation for ARGLIST is similar--it's also an environment
primitive.  X3J13 tried to de-emphasize the use of and requirements on
environment-related primitives as much as possible, and made a pretty
regular attempt not to add new ones.  DOCUMENTATION was retained for
compatibility with CLtL, but if it had not been present in CLtL I'm
pretty confident it would not have been added either.

My recollection is that there was a specific discussion at X3J13 of
adding ARGLIST or something similar.  As I recall, the discussion got
bogged down in issues of whether the priority should be on efficiency
(so that a meta-interpreter could be driven off the information) or
prettiness (so that the information could be useful to debugging).
These goals are pretty much at odds with each other, so without adding
several operators, it would have been tricky to satisfy them
simultaneously.  There are a lot of ways such a facility could have been
presented in the language, and there were frankly much higher priority
things to work on, so rather than fuss over endless details, I think it
just kind of fell off of our queue.

I hope this information is helpful to you in putting the situation into
proper perspective.