[Top][All Lists]

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

Re: docstring work

From: Keisuke Nishida
Subject: Re: docstring work
Date: Sun, 11 Feb 2001 23:27:51 -0500
User-agent: Wanderlust/2.4.0 (Rio) SEMI/1.13.7 (Awazu) FLIM/1.13.2 (Kasanui) Emacs/21.0.96 (i686-pc-linux-gnu) MULE/5.0 (SAKAKI)

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.
> 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")
  ($atan2 . (79035 . 102))
  ($expt . (78933 . 101))
  (%library-dir . (64078 . 205))
  (%make-void-port . (93417 . 313))
  (%package-data-dir . (63828 . 249))

((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.


reply via email to

[Prev in Thread] Current Thread [Next in Thread]