[Openmcl-devel] docstrings

[Gary Byers]

On Thu, 6 Jan 2005, bryan o'connor wrote:

> from ~2 years ago:
> > In ccl::level-0;l0-def.lisp, we have:
> >
> > (defun bootstrapping-set-documentation (symbol doc-type doc-string)
> >   (declare (ignore symbol doc-type doc-string))
> >    string)
> >
> > and cruft to make that be what happens when (SETF DOCUMENTATION)
> > is invoked.  That definition stays in effect until fairly late
> > in the loading sequence.
> >
> > I'm fairly sure that that could be made to work (in much the
> > same way that source file information's retained during the
> > cold load, but I'd agree that there probably aren't that many
> > doc strings getting ignored.
>
> i was looking into adding docstrings to all the cl-user symbols
> and maybe cleaning up some arglists to be more descriptive.  as
> i understand, both sbcl and cmucl are licensed such that we can
> start with their docstrings.
>
> i imagine the right thing to do is to add the docstrings to the
> source and have them by default be dumped in the image.  there'd
> also be a way to not include them to save space.  i think sbcl does
> this by simply adding a #+sb-doc before all their docstrings.
>
> would this be a good way to go?
>

The tricky part (if I remember the issues correctly) is getting
doc strings for the stuff in the level-0/directory to work.  The
FASL files in that directory are "loaded" into a pseudo-memory
image in a running lisp (via XLOAD-LEVEL-0), and a tweaked verion
of the fasloader tries to emulate the effect of loading the fasl
files on that artificial memory image.  If doc strings were stored
in a hash table (as they are later on in the loading sequence),
XLOAD-LEVEL-0 would have to be taught how to build an initialized
hash table into the bootstrapping image.  (Not impossible, but
the chicken-and-egg excuse is "but there aren't any doc strings
in level-0."  Of course there aren't: there's no support for them
in XLOAD-LEVEL-0 ...)