I'm not going to solve any problems here, but
(a) Some of the real experts have already documented
the code, and the post-1982 improvements to it as
well. We just don't have that material, and it
is discouraging to re-do it. Bug fixes and docs.
(b) Some of the documentation should be
"dont use this program... it does the same
thing as xxx but the author didn't know about
that other thing"
(c) information that is automatically produced
is very voluminous. All global variables and
places they are referenced, bound, set. All dependencies
of programs... There are sophisticated tools for
looking at large data sets (from Xerox PARC), but
these are kind of "data mining" (ugh! hate that term)
programs. The data here was produced by
hand and could be explained better.
(d) There is a somewhat parallel effort in the
Axiom community to document their code. Their
take on it is to try something like noweb (literate
programming).
(e) I have suggested repeatedly that there should
be a list of all error and warning messages and
explanations. (Mathematica has this).
(f) For many programs, I suspect it is easier
to write a simpler correct program than to explain
the existing program. This is very tricky because
if you don't really understand a program, you might
simplify it into something incorrect.
RJF
C Y wrote:
> --- Jesper Harder <harder@ifa.au.dk> wrote:
>
>>C Y <smustudent1@yahoo.com> writes:
>>
>>
>>>--- Jesper Harder <harder@ifa.au.dk> wrote:
>>>[docstrings]
>>>
>>>My main concern is that we have a framework within which we need to
>>>work - namely the describe command in maxima. Ideally I'd like the
>>>comments we have in the source code documenting functions serve a
>>>dual purpose as the material for the describe command and the
>>
> system
>
>>>manual. Would documentaion strings allow us to do that?
>>
>>Yes. But whether they're a good idea might depend on how good we'd
>>like the manual to be.
>>
>>If we want to put the documentation in the source, then I think
>>doc-strings is the obvious approach to try.
>>
>>The drawback is that manuals produced this way are usually not as
>>good as the ones written separately from source documentation.
>>They're useful but not excellent -- it's hard to write a really good
>>coherent document, when the content is scattered across hundreds of
>>source files.
>>
>>(although there are some notable exceptions, such as The TeX book).
>
>
> 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. Or maybe discuss the overall setup at the
> beginning of each chapter. That way if one wants the specifics on a
> particular function they can go straight to it and get the details. The
> user manual will (someday) do the job of being a coherent discussion of
> the system and how to use it - the system manual is to document all the
> nasty little details that make up the program. The only real trick
> will be organizing where each function should show up in the system
> manual. See below for my thinking on that.
>
>
>>>I definitely want to avoid inventing a new method if possible. It
>>>looks like acl2 successfully makes use of doc strings, so that
>>
> might
>
>>>be a guide, but we would need to be sure we can both use our
>>>describe system with doc-string information
>>
>>The doc-strings are already available from Maxima, try:
>>
>>(C1) :lisp (documentation '$context 'variable)
>
>
> Right, but the avarage end user isn't gonna like that unless they're
> all as smart as Richard :-). We'll have to juice up the describe
> command to handle that stuff. Shouldn't be too hard from the looks of
> that example. Or maybe we could parse to info format. Anyway one of
> the two will work.
>
>
>>>and generate texi source from it in some systematic fashion. I
>>>don't know how much work that would be, but I suppose it is doable.
>>
>>Extracting doc-strings and converting to texi is pretty easy. Try
>>this from the Maxima Lisp prompt:
>>
>>(with-open-file (s (merge-pathnames "maxima-vars.texi") :direction
>>:output :if-exists :supersede)
>> (do-symbols (var (find-package 'maxima))
>> (when (documentation var 'variable)
>> (format s "@defvar ~A~%~A~%@end defvar~2%" var
>> (documentation var 'variable)))))
>>
>>which extracts doc-strings from all Maxima variables that have one
>>and writes them to the file 'maxima-vars.texi'. This is nearly a
>>valid Texinfo file. You just need to take care of characters which
>>are special in Texinfo, such as '{', '}' and '@'.
>
>
> Sweet!! That's a very encouraging sign :-).
>
>
>>It doesn't address how to arrange the descriptions in a meaningful
>>way into chapters and sections, though.
>
>
> 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)
>
> It's possible to get by without it but that means the output will need
> to be formatted at another level to avoide having one long string
> appear onscreen.
>
> 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. Then when
> we go to generate the texi stuff, we check for each function what it's
> chapter variable is, and assign it to the proper place according to
> that variable. It's drawback is that it is somewhat inflexible if we
> want to reorganize things, but since if we wanted to do that we'd have
> to re-evaluate everything anyway I suspect it's about as good as we
> will get. Hopefully if we are careful with our initial organization we
> will only need to do it once, and new stuff will either fit into an
> established category or work in it's own.
>
> Does that sound workable or am I up too late again? :-)
>
>
>>>Is there a good tutorial on using doc strings somewhere?
>>
>>There isn't a lot to learn :-) If you supply a doc-string when a
>>function (or variable etc) is defined, e.g.
>>
>> (defun foo ()
>> "This function always returns T."
>> t)
>>
>>then that doc-string is available with the 'documentation' function:
>>
>> * (documentation 'foo 'function)
>> ==> "This function always returns T."
>
>
> Boy, I wish more of this was that straightforward! Awesome stuff
> Jesper!
>
> CY
>
> __________________________________________________
> Do you Yahoo!?
> Yahoo! Mail Plus - Powerful. Affordable. Sign up now.
> http://mailplus.yahoo.com
> _______________________________________________
> Maxima mailing list
> Maxima@www.math.utexas.edu
> http://www.math.utexas.edu/mailman/listinfo/maxima