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