[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: docstring work
From: |
Neil Jerram |
Subject: |
Re: docstring work |
Date: |
10 Feb 2001 12:58:59 +0000 |
>>>>> "Martin" == Martin Grabmueller <address@hidden> writes:
Martin> If you read bug-guile, you have seen the bunch of
Martin> docstrings I have already send in; if not you could have a
Martin> look at the archives. It would be nice if someone could
Martin> review them, especially if he/she is a native speaker.
Martin> Technically I got the docstrings correct (I hope), but
Martin> grammatically...
Right, I will do this review. According to the libguile ChangeLog in
CVS, there is an entry for a docstring patch from you on 2001-01-29,
for docstrings in struct.c. Are there other patches that are pending
in bug-guile?
>> I also have ideas on extending the docstring mechanism to cover
>> more stuff, and to support i18n. If you're interested, let me
>> know and I'll pull together a description.
Martin> That would be very nice.
Here goes. This is all IMO, of course.
1. It would be nice to extend the C snarfing macros to cover things
other than primitive procedures, e.g. macros, symbols, hooks and
concepts.
Imagine...
guile> (help 'threads)
Threads are a concept provided by the (guile) module.
- concept: Threads
Threads enable an application to run multiple lines of execution
apparently in parallel. ...
Guile presents a consistent interface to threads that is
independent of the underlying implementation.
For further details, see `begin-thread'.
Libguile already contains a lot of conceptual documentation, in the
form of extended comments, that could be used for such docstrings.
I believe that SCWM already has something like this, so we check out
how SCWM does it.
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.
I think we should also support snarfing docstrings from Scheme module
files. Instead of:
(define (purify-module! module)
"Removes bindings in MODULE which are inherited from the (guile) module."
...)
we would use a format like:
;;; Removes bindings in @var{module} which are inherited from the
;;; (guile) module.
(define (purify-module! module)
...)
Advantages are:
- reducing the occupancy of loaded Scheme code
- collecting the snarfed docstrings together in a form amenable for
translation.
Docstrings snarfed in this way would be stored in per-module doc
files, which brings me on to ...
3. Currently there is only one doc file -- guile-procedures.txt --
which is the result of snarfing C docstrings from libguile. Once we
have snarfed docstrings coming from Scheme files as well, I think that
docstrings should be organised by module and per-module doc files
located in the same filesystem hierarchy as the module files
themselves. Doc files would be named according to module name. So
guile-procedures.txt, which contains docstrings for the (guile)
module, would become guile.doc and be installed at
<prefix>/share/guile/<version>/guile.doc.
This fits well with the way that name lookup works in (ice-9 session):
the procedures here know the module that a name belongs to.
4. Doc files can be translated into other languages. We should
support translated doc files by
- defining where they should installed:
e.g. <prefix>/share/guile/<version>/<locale>/guile.doc
- modifying the look up code to try a path with the current locale in
before the path without locale.
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.
Best regards,
Neil
Re: docstring work, Greg Badros, 2001/02/15