Documenting liboctave

[John W. Eaton]

On 14-Feb-2000, Matthew W. Roberts <address@hidden> wrote:

| Well, I was going to sit down and write a C++ encapsulation of LAPACK
| when I realized that liboctave has already done that.  As you know, the
| documentation is rather sparse, so I will be digging into the code to
| figure out exactly what some of the methods do.
| 
| While I'm at it, I figure I could take a little extra time and document
| what I find.  Is that something that would be helpful?

Yes.  The documentation in doc/liboctave is quite out of date.

| If so, I need to know what conventions you use.  I noticed you have
| DEFUN* macros defined which allow for documentation within the source.
| They don't seem to be used with liboctave, though.

They are for declaring functions that can be called from the Octave
command line, not for library functions.

It might be nice to also document the functions in liboctave in the
source code and then extract that information for the manual.  It
should not be too difficult to do it in a way that is similar to what
is currently done with the .m files.  The doc strings could go in
comments and then be extracted by some simple sed commands.  If we are
going to do this, I have some preferences.  The doc strings should be
written in Texinfo, and they must be organized (probably by hand,
since I think it is not possible otherwise) in a reasonable way in the
manual, with sufficient supporting text to help explain why the
functions are being described together.  A laundry list of function
descriptions makes a lousy manual...

Thanks,

jwe



-----------------------------------------------------------------------
Octave is freely available under the terms of the GNU GPL.

Octave's home on the web:  http://www.che.wisc.edu/octave/octave.html
How to fund new projects:  http://www.che.wisc.edu/octave/funding.html
Subscription information:  http://www.che.wisc.edu/octave/archive.html
-----------------------------------------------------------------------