Re: Documenting Octave Source

[JD Cole]

Hi folks,
   Let me try to answer a couple of things:

1) Although there may be a number of locations on the web that have 
"doxygenated" octave source code, it seems that they have used doxygen 
in the same way which I was suggesting to those who are introducing 
themselves to octave internal, as a means to understanding code 
structure. (It should be noted that it is quite easy to generated such 
documentation, a little editing of the doxygen config file and your 
flying. This is the power of doxygen.) As such, I would hasten to say 
that many actual comments have actually been added to the "docs" already 
generated. I took a quick look at the link from northwestern, and it 
seems this way.

2) Recently there has been some talk about adding an abstraction layer 
between the main octave source and .oct files. While the main motivation 
behind this may be for stability of .oct's between octave releases, it 
will also somewhat limit what .oct designer *should* use to design their 
files. (I must admit I'm an abuser of using .oct files as a way test 
internal changes in octave for the simplicity of recompilation.)
   What I'm driving at here is that, I don't think it is really 
necessary to provide the doxygen output, i.e. html, tex, or whatever, 
via the web, at least, not in its expanded form, perhaps as an archive. 
Since its main goal, in my opinion, is to introduce and assist people 
working on octave internals, it really has a somewhat small audience. I 
think some reference to the fact that source code documentation exists 
and can be easily built is plenty to satisfy the user.
   There are a couple motivating factors here, one is that due to the 
sheer size of the code base, people using the html-doxygen pages via the 
web will cause a substantial load on your server. (This is my little 
political thing that we all have a responsibility to not tax the 
internet any more than necessary, every little bit counts, even in our 
little world.) Secondly, the files are big, and it is to their 
advantage, speed wise, to use them locally. Just check out the online 
docs for VTK (http://www.vtk.org/doc/release/4.0/html). Much like when 
we drum through source code looking for connections, the same will 
happen with these docs, especially given the ease following execution 
paths with the click of a button.

3) On the topic of generating the documentation. Typically the placement 
of a doxygen config file in your main source directly should suffice. 
After it has been properly setup, in it's simplest form pointing doxygen 
at the correct directories and file types, generating the docs is as 
simple as typing

doxygen  octave.doxy

or the like. I think the only addition to the Octave Makefile would be 
something like:

code-docs:
   doxygen octave.doxy

I suppose that depencies for every .h and .cc file code be added, but it 
may be better for the developer to use their own discretion when 
regenerating since the process takes a bit of time. (Admittedly it is 
much shorter than actually recompiling octave source.)

4) On commenting the source. When I originally mentioned adding comments 
to the source, my intention was aimed at function-level descriptions, 
not line-by-line docs. Doxygen comments can be made in a few different 
forms, with a lot of different options, but basically would look 
something like this:

/// This is a one liner documentation string, notice the 3 /'s
/**
* Multiline docs come in this form, starting with /**
* keywords can be added to do some special documenting, such as
* @param argc The number of command line argument appearing in argv
* @param argv A string array of command line arguments
* other things like this can be added
* @see octave_main
*/
int
main (int argc, char *argv [])
{
}

Similar formats exist for structures, class definitions, and the works.

-JD

Paul Thomas wrote:

> John,
>
> The latest that I have found, which is more than adequate for persuing 
> the structure of octave, is version 2.1.39 on
>
> http://www.fluids.mech.northwestern.edu/~shreyas/octave/
>
> I do not have the means to post such documentation since our website 
> at work is behind several firewalls.  The security provided by my ISP 
> is such that I do not want to draw attention to my account by having a 
> private site!
>
> Perhaps one of the folk that were telling us how to do it could 
> provide a link to Doxygen documentation of 2.1.55?  It is likely to be 
> useful for a long time, since the structure evolves relatively slowly 
> and so the job would nearly be a one-off.