This is the mail archive of the guile@cygnus.com mailing list for the guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: Scheme documentation question


Tel <telford@eng.uts.edu.au> wrote:
> Is anything wrong with:
> 
> (document-variable VAR DOC-STRING)
> 
> OK, I'll admit that you must type the variable name twice
> and you might spell it wrong the second time, but why go for
> something complicated when something simple will work?
> Is it necessary for one function to do everything?

I like this idea. In fact, it might even make sense to extend it to document
functions as well, because this way you can add flexibility to the
documentation system.

Possible extensions:

(document-variable VAR DOC-STRING 
                   &opt CHAPTER-HIERARCHY 
                        SEE-ALSO-LIST)
(document-function FUNCTION DOC-STRING 
                   &OPT PARAM-DESCRIPTION-ALIST 
                        CHAPTER-HIERARCHY 
                        SEE-ALSO-LIST)

By separating functions and documentation we get added flexibility and make
parsing and documentation extraction easier. We could even put documentation
and code into different files (it is questionable if this is a good idea in
general, however, in some cases it might be).

It is also less intrusive to add documentation to code: You don't have to use
define-public just to be able to add your documentation strings. Documentation
is cleanly separated and can be provided by a module without need to include
it in the core during startup. This seems better to me than to deeply embed
documentation support within the very basic functions/macros like it is done
with define-public.

By redefining the document-xxx functions, users have even more fine-grained
control over which documentation is to be stored and which can safely be
abandoned. This may be an issue if lots of modules are loaded and the loaded
doc strings eat a lot of memory or additional GC time overhead.

Summarized: this way, documentation is easily and flexibly generated by
developers, extracted by parsers and customized by guile users.

Best regards, 
Dirk Herrmann