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