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