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


Dirk Herrmann <dirk@ida.ing.tu-bs.de> writes:

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

IMHO documentation belongs either right next to the code, or in the
manual.  So I actually prefer the Emacs style:

  (define (foo x)
    "Documentation for function foo."
    (string-append x "foo"))

as opposed to:

  (define (foo x)
    (string-append x "foo"))
  (document-function foo "Documentation for function foo.")

For variables I would prefer a new macro that worked something like this:

  (defvar *some-global-var* 23
    "Documentation for this variable.")

Yes, I know that I'm hopelessly following the Emacs tradition.  I'm
used to it, and I like it.  The SEE-ALSO-LIST is a neat idea, and the
other might be also, if I could imagine more specifically how they
would be used.

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

It works with regular 'define' too.

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

I agree that it is nice to have the documenation strings somewhere
outside of core, but I actually prefer to have the documentation right
in there.  The optimal solution IMHO would have both of these features.

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

Actually, having the doc strings right inside of Lisp forms at defined
locations is also quite easy to parse.

-russ

--
The optimist thinks this is the best of all possible worlds. The
pessimist fears it is true.	
             -- Robert Oppenheimer