Re: Scheme documentation question

[Tel <telford@eng.uts.edu.au>]

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

Let's just say that the option remains open.

It is nice if the documentation can include a copy of the argument
template for the function, you need the real function definition to get
that (because you don't want to have to write out the argument template
twice, that's highly prone to error). With scheme, it's reasonably easy
to scan out argument templates from the code so even if they are in
separate files, bringing the two together is easy enough. I really would
like a compiler option that went through my C stuff and extracted the
argument templates but C has typedefs so you just about need to compile
the thing before you know what's what. At the moment I'm just copying the
argument templates by hand into the documentation.

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

Well I was thinking of defining it to do nothing in many cases like
for running script files when online documentation is really not an issue.

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

Thanks, glad you liked it!

	- Tel