C Y <smustudent1@yahoo.com> writes:
> What I had in mind (again this is just me waving my hands) is to
> document each function/variable at a local level, generate chapters
> from that, and then at the beginning write the bird's eye overview of
> how the pieces fit together.
OK. One way to do that would be to insert a magic comment in the manual,
where you want a docstring to appear, and then pre-process the texi
source to get the docstring inserted.
E.g. you could write
@c TEXI DOCSTRING MAGIC: context
to get the docstring for 'context' wrapped up in proper Texinfo markup.
Take a look at 'texi-docstring-magic.el' which does exactly this for
Emacs Lisp:
<http://www.proofgeneral.org/ProofGeneral-latest/generic/texi-docstring-magic.el>;
> Ah, there's the rub. And it also brings up indirectly another question
> - whether or not you can have multiple line doc strings. I.e., can we
> do something like:
>
> (defun foo ()
> "Author: John Doe
> Functionality: This function always returns T."
> t)
Sure. They can be as long as you like. In carefully documented code
they can be quite long. Here's a random example:
<http://www.norvig.com/java-lisp.html>;
> As for chapter layout, my idea works something like the following:
> define a local variable in each function/variable/etc. called topic or
> chapter or something, and assign it a value like integration,
> simplification, general, etc - something that makes sense.
This means that we will have to do the classification one way or
another. I think it's simpler to do it in the manual rather than in the
source files.
Do you know the Mathematica manual? It has an appendix with a listing
of all built-in Mathematica objects with a short explanation of each
item. That could be a different way of using docstrings.