Re: docstring work

[Keisuke Nishida]

At 10 Feb 2001 12:58:59 +0000,
Neil Jerram wrote:
> 
> 2. Currently the only snarfed docstrings come from the C code for
> libguile.  Documentation for Scheme-defined procedures is extracted
> from the lambda body, where the first expression of the lambda body is
> a string.
(snip)
> we would use a format like:
> 
> ;;; Removes bindings in @var{module} which are inherited from the
> ;;; (guile) module.
> (define (purify-module! module)
>   ...)

I personally prefer this comment style docstrings even in C files.
It's more flexible because we can add more information than docstrings,
such as the author of the function, the day written, deprecated flags
(and when it should be removed), etc.

> 5. Performance improvements.  Currently, to look up 10 docstrings in
> guile-procedures.txt, we open and read through guile-procedures.txt 10
> times.  Some caching work here may be worthwhile.

I worked on an improvement in the past, in which I used a simple
dictionary format like this:

------------------------------------------------------------------------
((title . "Guile docstrings")
 (index
  ($atan2 . (79035 . 102))
  ($expt . (78933 . 101))
  (%library-dir . (64078 . 205))
  (%make-void-port . (93417 . 313))
  (%package-data-dir . (63828 . 249))
  ...
[snip]

((name . acons)
 (type . primitive-procedure)
 (args key value alist)
 (file . "$(LIBGUILE)/alist.c:61"))
Adds a new key-value pair to @var{alist}.  A new pair is
created whose car is @var{key} and whose cdr is @var{value}, and the
pair is consed onto @var{alist}, and the new list is returned.  This
function is @emph{not} destructive; @var{alist} is not modified.

((name . sloppy-assq)
 (type . primitive-procedure)
 (args key alist)
 (file . "$(LIBGUILE)/alist.c:84"))
Behaves like @code{assq} but does not do any error checking.
Recommended only for use in Guile internals.

...

------------------------------------------------------------------------

The index part is cached and looking up a docstring is quote fast.

If you are interested, I'll send you a copy of code or I'll continue
to work on this.

Kei