Subject: Seeking areas of little or weak documentation
From: Rupert Swarbrick
Date: Mon, 21 Mar 2011 22:34:30 +0000
Oliver Kullmann <O.Kullmann at swansea.ac.uk> writes:
> I think a great thing for Maxima would be if one could
> teach Doxygen (http://www.stack.nl/~dimitri/doxygen/)
> to understand the Maxima language (and/or Lisp).
>
> This would be a meta-tool, potentially extremely helpful.
>
> Oliver
>
> P.S. Doxygen doesn't have great support for new languages,
> but it suports quite a lot, and as far as I know, basic
> support for Lisp-like languages shouldn't be too hard to
> add (there are language-templates).
Hmm, I'm not convinced. I think that most of Maxima's internal functions
could be documented via docstrings in the lisp code: the fact that they
aren't isn't due to a tooling problem!
The user-level documentation should definitely not be written with
doxygen: the results are invariably hard to read as a "manual", rather
than a reference / list of function prototypes.
Maybe this comes across as dogmatic, but I can't think of any open
source project with nice doxygen-genarated documentation and I know that
my first reaction when I see the characteristic blue tabs along the top
is to groan out loud...
Rupert
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 315 bytes
Desc: not available
URL: <http://www.math.utexas.edu/pipermail/maxima/attachments/20110321/1e626e61/attachment.pgp>;