Documenting Octave Source

classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

Documenting Octave Source

JD Cole
    Would anyone be opposed to adding more thorough documentation to the
Octave source code. I know when I go through the sources to try to
implement something new, there's a lot of "discovery" going on, as with
any large body of code. I often make comments for myself, but I would
happily donate such comments to the project if they are correct. This
would, of course, be somewhat of a piecemail process, I wouldn't expect
anyone to go through each source file and comment on each function, but
I'm sure the results would accumulate over time.
    As you have probably read, I have suggested that new Octave hackers
use doxygen to get a better grip on class dependencies, etc. Adding
comments in a format accepted by doxygen would definitely expedite the
learning process, not to mention benefit bug fixing and implementation.

Any thoughts?

JD


Reply | Threaded
Open this post in threaded view
|

Re: Documenting Octave Source

Paul Thomas-10
JD,

That is an excellent idea.  There are already some sites that post
Doxygen documentation of Octave;
eg.
http://dionysos.univ-lyon2.fr/~dsarrut/src-doc/octave/html/classtree__expression.html

There are more recent, English versions of octave posted out there but
for some reason the web is moving VERY slowly this morning so I couldn't
verify them.

Could such documentation be posted on the octave site, John?

Paul Thomas


JD Cole wrote:

>    Would anyone be opposed to adding more thorough documentation to
> the Octave source code. I know when I go through the sources to try to
> implement something new, there's a lot of "discovery" going on, as
> with any large body of code. I often make comments for myself, but I
> would happily donate such comments to the project if they are correct.
> This would, of course, be somewhat of a piecemail process, I wouldn't
> expect anyone to go through each source file and comment on each
> function, but I'm sure the results would accumulate over time.
>    As you have probably read, I have suggested that new Octave hackers
> use doxygen to get a better grip on class dependencies, etc. Adding
> comments in a format accepted by doxygen would definitely expedite the
> learning process, not to mention benefit bug fixing and implementation.
>
> Any thoughts?
>
> JD
>
>



Reply | Threaded
Open this post in threaded view
|

Re: Documenting Octave Source

JD Cole
Paul,
    This, of course, is a very easy plan to implement, it just needs the
blessing of "he who holds the keys to the  city [cvs]". Hint, hint....

    I think to reduce the amount of work that jwe would have to do in
order to integrate comments such as these, it should be the
responsibility of the of contributor to ONLY give diffs for the comments
and make sure that it is with respect to the CURRENT cvs.

JD

Paul Thomas wrote:

> JD,
>
> That is an excellent idea.  There are already some sites that post
> Doxygen documentation of Octave;
> eg.
> http://dionysos.univ-lyon2.fr/~dsarrut/src-doc/octave/html/classtree__expression.html 
>
>
> There are more recent, English versions of octave posted out there but
> for some reason the web is moving VERY slowly this morning so I
> couldn't verify them.
>
> Could such documentation be posted on the octave site, John?
>



Reply | Threaded
Open this post in threaded view
|

Octave-> C++

Jens Ruecknagel-2
In reply to this post by JD Cole
Hi,

I talked to my professor, I am doing during the next month the C++ Code
generator as a Student research project. The Code is going to be
developed as open source and is going to be contributed to the Octave
project. There is also no problem to help me in any way. I can do an
open source project as student research project.

Thanks to the support by JD Cole I have some idea what to do.
I already started, I took the pt-pr-code.* and started to develop a C++
Code generator. I also get some ideas from the evaluator.

Jens


Reply | Threaded
Open this post in threaded view
|

Re: Octave-> C++

JD Cole
Glad to hear it Jens!

  To the others who have been involved in the discussion about an Octave
compiler, I made the suggestion to Jens that he a more simple approach to
generating C++ from .m source. While we should all continue to discuss a grand
view of things, JIT .m -> straight C++, etc. , I think his contribution will be
an excellent starting point in this area.

Thanks for re-awakening this idea Jens!

JD

Quoting Jens Ruecknagel <[hidden email]>:

> Hi,
>
> I talked to my professor, I am doing during the next month the C++ Code
> generator as a Student research project. The Code is going to be
> developed as open source and is going to be contributed to the Octave
> project. There is also no problem to help me in any way. I can do an
> open source project as student research project.
>
> Thanks to the support by JD Cole I have some idea what to do.
> I already started, I took the pt-pr-code.* and started to develop a C++
> Code generator. I also get some ideas from the evaluator.
>
> Jens
>
>




Reply | Threaded
Open this post in threaded view
|

Re: Documenting Octave Source

John W. Eaton-6
In reply to this post by JD Cole
On 27-Feb-2004, JD Cole <[hidden email]> wrote:

|     This, of course, is a very easy plan to implement, it just needs the
| blessing of "he who holds the keys to the  city [cvs]". Hint, hint....
|
|     I think to reduce the amount of work that jwe would have to do in
| order to integrate comments such as these, it should be the
| responsibility of the of contributor to ONLY give diffs for the comments
| and make sure that it is with respect to the CURRENT cvs.

I think the reason that Octave's source code doesn't have a lot of
comments is because the typical function is small and has a fairly
clear purpose.  This is not always true, and I often find that if I am
unable to understand what a function is doing by just reading the
code, it usually turns out that there is a simpler way to write the
code that makes it easy to understand.  I also find that trying to
write comments (or documentation) for a badly designed function tends
to make it clearer that the code is badly written.

In any case, I have no objection to patches that add comments provided
that

  * The comments are actually useful.  Meta-comments about the intent
    of a code block or the purpose of data members in a class are much
    more likely to be useful than comments on each line of code.

  * Match the formatting of the comments in the rest of Octave.  For
    example, please try to follow the guidelines of the GNU coding
    standards, but use C++ style comments.  Write about arguments by
    using their parameter names in all caps.

  * Use mostly complete sentences and puntuation.

  * Send patches with one patch per message with one set of comments
    about a single topic or bit of code.  It is too difficult to sort
    through a large patch and decide what to keep.  I'm already a
    major bottleneck in the process of getting patches into Octave, so
    any help you can provide to make the process easier is
    appreciated.

Thanks,

jwe


Reply | Threaded
Open this post in threaded view
|

Re: Documenting Octave Source

John W. Eaton-6
In reply to this post by Paul Thomas-10
On 27-Feb-2004, Paul Thomas <[hidden email]> wrote:

| That is an excellent idea.  There are already some sites that post
| Doxygen documentation of Octave;
| eg.
| http://dionysos.univ-lyon2.fr/~dsarrut/src-doc/octave/html/classtree__expression.html
|
| There are more recent, English versions of octave posted out there but
| for some reason the web is moving VERY slowly this morning so I couldn't
| verify them.
|
| Could such documentation be posted on the octave site, John?

This seems like a nice way to view the sources, but I'm afraid that I
don't have time to set it up and maintain it myself.

jwe


Reply | Threaded
Open this post in threaded view
|

Re: Documenting Octave Source

John W. Eaton-6
On  5-Mar-2004, John W. Eaton <[hidden email]> wrote:

| On 27-Feb-2004, Paul Thomas <[hidden email]> wrote:
|
| | That is an excellent idea.  There are already some sites that post
| | Doxygen documentation of Octave;
| | eg.
| | http://dionysos.univ-lyon2.fr/~dsarrut/src-doc/octave/html/classtree__expression.html
| |
| | There are more recent, English versions of octave posted out there but
| | for some reason the web is moving VERY slowly this morning so I couldn't
| | verify them.
| |
| | Could such documentation be posted on the octave site, John?
|
| This seems like a nice way to view the sources, but I'm afraid that I
| don't have time to set it up and maintain it myself.

Sorry to follow up to my own posting.

If someone automates the process of generating the docs from the
sources and puts those rules in the Octave Makefiles and links those
rules into the dist target so that we also create a tar file of
doxygen output files, then it would be easy to build the docs as a
part of making snapshot or release.  If building the doxygen files
were made simple, then I would be willing to put them on the web after
every snapshot.

Alternatively, we could build the doc files from the CVS archive and
update it more frequently, but someone will need to write the scripts
to do it as I don't have the time.

Thanks,

jwe


Reply | Threaded
Open this post in threaded view
|

Re: Documenting Octave Source

Paul Thomas-10
In reply to this post by John W. Eaton-6
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.

Paul

John W. Eaton wrote:

>On 27-Feb-2004, Paul Thomas <[hidden email]> wrote:
>
>| That is an excellent idea.  There are already some sites that post
>| Doxygen documentation of Octave;
>| eg.
>| http://dionysos.univ-lyon2.fr/~dsarrut/src-doc/octave/html/classtree__expression.html
>|
>| There are more recent, English versions of octave posted out there but
>| for some reason the web is moving VERY slowly this morning so I couldn't
>| verify them.
>|
>| Could such documentation be posted on the octave site, John?
>
>This seems like a nice way to view the sources, but I'm afraid that I
>don't have time to set it up and maintain it myself.
>
>jwe
>
>
>  
>



Reply | Threaded
Open this post in threaded view
|

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.
>