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] |
Clark McGrew wrote: > I would like to see a documentation property attached to both scheme > and primitive functions (and compiled into the executable). I find > it very useful when I'm hacking around to be able to get a quick > synopsis of a function. But, if the documentation is compiled into > the exe, then the doc strings should be short. I would tend to think this adds unnecessary bload to the binary, and would mean that the doc strings for subr's (implemented in C) and (in the future) byte-compiled scheme functions would be stored (and thus accessed, wrt lookup code) differently. I like the way emacs stores its doc strings in an indexed file generated at (byte) compile time -- despite the reservations some of you guys have... > I'd also like to see the reference documetation included in the > source. By source I mean a .h, .c, or .scm file. On the other hand, > I'd hate to see a move to literate programing since (I feel) it make > code completely unreadable. Agreed, on both counts. > Another problem with documentation in the source is that functions > tend to be in a "random" order. This could be solved by adding a > section tag to each annotation. > > This isn't a new idea, but how about a solution like this. > > In C: > > /* > (REFERENCE scheme-name (section-info) > This is for detailed reference documentation that describes how to use > the function. It goes into a user reference manual. The scheme-name > is the name of the scheme function being documented.) > > (PROGRAM C-name (section-info) > This is for detailed implementation documentation. It goes into a > programmers reference manual.) > */ > > static char s_scheme_func_doc[] = > "A short text synopsis attached to the documentation property" I really like this! But, for the reasons cited above, I would rather add: /* (DOCSTRING A short text synopsis attached to the documentation property) */ > In scheme: > > ;(REFERENCE scheme-name (section-info) > ; The detailed reference documentation goes here.) > (define scheme-name > (lambda () > "A short synopsis goes here." > ...)) This is cool, but to avoid the inevitable slowdown of parsing all of these embedded docstrings we *really* need byte-compilation which would extract the string to an index file of some sort. This is not just a "me too"! The thing that I thought would be really cool about this, is that the manuals and doc strings could be cross referenced by the extraction process... that is the doc string could have appended, e.g. "(ref manual pp.123, section 4.5)", or the reference manual could point out at the explanations in the user manual, e.g. "The use of this function is described in the user manual pp.. etc". > [[snip]] > > Cheers, > > Clark Yup! Cheers, Gary V. Vaughan
begin: vcard fn: Gary Vaughan n: Vaughan;Gary org: Aethos Communication Systems ltd. email;internet: gvaughan@oranda.demon.co.uk tel;work: 01454 - 204411 x-mozilla-cpt: ;0 x-mozilla-html: FALSE version: 2.1 end: vcard