profiler, doxygen, ...

[Julien Bect]

Dear all,

I have been trying to read the code of the profiler
(libinterp/interpfcn/profiler.cc) last night, to assess whether I could
be able to fix Bug #38480 myself, and found it rather hard to understand...

Looking for a little help, I remembered that there was a doxygen output
published somewhere on the web, and found this :

http://octave.sourceforge.net/doxygen/html/

First observation : I found no clear mention of the version this
documentation corresponds to. Perhaps I didn't look hard enough, but it
would be safer to mention it somewhere on *every* page of the
documentation, woudn't it ?

Second observation : the class 'profile_data_accumulator' is missing
from the class list... Looking at the source code of the HTML pages, I
found that they were generated in 2009, which explains why the profiler
is absent.

Is there a way to generate an up-to-date doxygen documentation as part
of Octave's build process (I found no mention of doxygen in the output
of ./configure -h) ?

Otherwise, is there a place where I can find a little help (and perhaps
a configuration file) to generate an up-to-date doxygen documentation
for myself ?

Best regards,

Julien.

[Jordi Gutiérrez Hermoso-2]

On 7 March 2013 03:24, Julien Bect <[hidden email]> wrote:
> Is there a way to generate an up-to-date doxygen documentation as part of
> Octave's build process (I found no mention of doxygen in the output of
> ./configure -h) ?

Bare-bones Doxygen output is very easy to generate. Just type
"doxygen" at the top-level directory. Their documentation is,
unsurprisingly, very good, so do read that too.

- Jordi G. H.

[Julien Bect]

On 07/03/2013 14:27, Jordi Gutiérrez Hermoso wrote:
> On 7 March 2013 03:24, Julien Bect <[hidden email]> wrote:
>> Is there a way to generate an up-to-date doxygen documentation as
>> part of Octave's build process (I found no mention of doxygen in the
>> output of ./configure -h) ?
> Bare-bones Doxygen output is very easy to generate. Just type
> "doxygen" at the top-level directory.

It doesn't work for me :

$ doxygen
Doxyfile not found and no input file specified!
Doxygen version 1.8.1.2
Copyright Dimitri van Heesch 1997-2012
You can use doxygen in a number of ways:
...

> Their documentation is, unsurprisingly, very good, so do read that
> too. - Jordi G. H.

Of course, I could do that, and I will eventually. (This is not a very
helpful answer.)

But, since doxygen apparently needs some configuration files to produce
a nice-looking output like http://octave.sourceforge.net/doxygen/html,
and since somebody somewhere probably has these configuration files, I
thought it might be a good idea to ask this list first.

[Jordi Gutiérrez Hermoso-2]

On 7 March 2013 10:05, Julien Bect <[hidden email]> wrote:

> On 07/03/2013 14:27, Jordi Gutiérrez Hermoso wrote:
>>
>> On 7 March 2013 03:24, Julien Bect <[hidden email]> wrote:
>>>
>>> Is there a way to generate an up-to-date doxygen documentation as part of
>>> Octave's build process (I found no mention of doxygen in the output of
>>> ./configure -h) ?
>>
>> Bare-bones Doxygen output is very easy to generate. Just type "doxygen" at
>> the top-level directory.
>
>
> It doesn't work for me :
>
> $ doxygen
> Doxyfile not found and no input file specified!
> Doxygen version 1.8.1.2
> Copyright Dimitri van Heesch 1997-2012
> You can use doxygen in a number of ways:
> ...

Read the part that you tl;dr'ed. It tells you right there how to
generate a configuration file.

- Jordi G. H.

[Carnë Draug-2]

On 7 March 2013 15:05, Julien Bect <[hidden email]> wrote:
>
> But, since doxygen apparently needs some configuration files to produce a
> nice-looking output like http://octave.sourceforge.net/doxygen/html, and
> since somebody somewhere probably has these configuration files, I thought
> it might be a good idea to ask this list first.

Those were generated a long time ago, and I believe created by Søren
(CC'ed on this email) since he was the Octave Forge maintainer at the
time. While I have been updating the list of Octave functions with
each release, I have not done so for the doxygen as I do not know how
and had never use for it.

At the moment, I do not have the time to figure out how to do it
myself but if someone prepares a tarball with it, I'll gladly replace
the files on the server.

Carnë

[Jordi Gutiérrez Hermoso-2]

On 7 March 2013 10:05, Julien Bect <[hidden email]> wrote:
> But, since doxygen apparently needs some configuration files to produce a
> nice-looking output like http://octave.sourceforge.net/doxygen/html,

No, that requires no configuration really. The default config works.
There's some custom CSS there, but that's unrelated to Doxygen.

- Jordi G. H.

[Jordi Gutiérrez Hermoso-2]

On 7 March 2013 10:19, Jordi Gutiérrez Hermoso <[hidden email]> wrote:
> On 7 March 2013 10:05, Julien Bect <[hidden email]> wrote:
>> But, since doxygen apparently needs some configuration files to produce a
>> nice-looking output like http://octave.sourceforge.net/doxygen/html,
>
> No, that requires no configuration really. The default config works.
> There's some custom CSS there, but that's unrelated to Doxygen.

Looks like the default config has changed since last time I used
doxygen. I made some small adjustments. Attached is the Doxyfile I
used.

I don't find bare-bones doxygen output to be very useful since the
Octave class hierarchy is so messy, but here it is:

    http://jordi.platinum.linux.pl/tmp/oct-doxy.zip
    http://jordi.platinum.linux.pl/tmp/oct-doxy/d6/d68/classoctave__base__value.html

Note the /tmp/ in those urls. I don't guarantee the stability of these
urls.

- Jordi G. H.

[Júlio Hoffimann]

I personally dislike Doxygen documentation, it's not so different than reading the source itself. Plus, if you properly configure your IDE or advanced text editor (VIM / EMACS), you can jump across definitions very easily.

Please don't pollute Octave source code with Doxygen comments. :)

Best,

Júlio.

[Jordi Gutiérrez Hermoso-2]

On 7 March 2013 10:56, Júlio Hoffimann <[hidden email]> wrote:
> I personally dislike Doxygen documentation, it's not so different than
> reading the source itself.

Well, sometimes it would be nice if the source itself were commented
so I could know wtf is going on. Most of the time I figure this out by
stepping with gdb.

I agree that for Octave, reading the Doxygen output isn't much better
than reading the source code.

> Plus, if you properly configure your IDE or advanced text editor
> (VIM / EMACS), you can jump across definitions very easily.

That's typically what I do too.

> Please don't pollute Octave source code with Doxygen comments. :)

I just wish we had more comments of any kind:

    https://www.ohloh.net/p/octave/analyses/latest/languages_summary

If we were to comment the Octave source code too, I don't see much of
a problem formatting those comments for Doxygen. If GNU libstdc++ does
it, why not us?

- Jordi G. H.

[Carnë Draug-2]

On 7 March 2013 15:53, Jordi Gutiérrez Hermoso <[hidden email]> wrote:

> On 7 March 2013 10:19, Jordi Gutiérrez Hermoso <[hidden email]> wrote:
>> On 7 March 2013 10:05, Julien Bect <[hidden email]> wrote:
>>> But, since doxygen apparently needs some configuration files to produce a
>>> nice-looking output like http://octave.sourceforge.net/doxygen/html,
>>
>> No, that requires no configuration really. The default config works.
>> There's some custom CSS there, but that's unrelated to Doxygen.
>
> Looks like the default config has changed since last time I used
> doxygen. I made some small adjustments. Attached is the Doxyfile I
> used.
>
> I don't find bare-bones doxygen output to be very useful since the
> Octave class hierarchy is so messy, but here it is:
>
>     http://jordi.platinum.linux.pl/tmp/oct-doxy.zip
>     http://jordi.platinum.linux.pl/tmp/oct-doxy/d6/d68/classoctave__base__value.html
>

I have updated http://octave.sourceforge.net/doxygen/html/

Would be nice if someone fixed the style issues.

Carnë

[Júlio Hoffimann]

I just wish we had more comments of any kind:

    https://www.ohloh.net/p/octave/analyses/latest/languages_summary

If we were to comment the Octave source code too, I don't see much of
a problem formatting those comments for Doxygen. If GNU libstdc++ does
it, why not us?

- Jordi G. H.

Yeah, comments are awesome, especially if short and objective. C++ is enough boilerplate, Doxygen adds boilerplate to the comments, lol.

This is what makes C++ so special, you can make it unreadable as you want, no bounds.

Júlio.

[Jordi Gutiérrez Hermoso-2]

On 7 March 2013 11:32, Carnë Draug <[hidden email]> wrote:
> I have updated http://octave.sourceforge.net/doxygen/html/

So that was doxygen output for 16201:743b895259e0. Perhaps I should
generate it for the stable branch instead? I'm not sure we should have
an unstable "API" being publicly documented like that.

> Would be nice if someone fixed the style issues.

It shouldn't be too difficult, but I'm not interested myself.

- Jordi G. H.

[Carnë Draug-4]

On 7 March 2013 17:00, Jordi Gutiérrez Hermoso <[hidden email]> wrote:
> On 7 March 2013 11:32, Carnë Draug <[hidden email]> wrote:
>> I have updated http://octave.sourceforge.net/doxygen/html/
>
> So that was doxygen output for 16201:743b895259e0. Perhaps I should
> generate it for the stable branch instead? I'm not sure we should have
> an unstable "API" being publicly documented like that.

Yes please. I thought it was the API for the 3.6.X series. Just for
the record, the doxygen  for the previous versions is available at

http://octave.sourceforge.net/doxygen32/html/
http://octave.sourceforge.net/doxygen34/html/

Carnë

[Jordi Gutiérrez Hermoso-2]

On 7 March 2013 12:14, Carnë Draug <[hidden email]> wrote:

> On 7 March 2013 17:00, Jordi Gutiérrez Hermoso <[hidden email]> wrote:
>> On 7 March 2013 11:32, Carnë Draug <[hidden email]> wrote:
>>> I have updated http://octave.sourceforge.net/doxygen/html/
>>
>> So that was doxygen output for 16201:743b895259e0. Perhaps I should
>> generate it for the stable branch instead? I'm not sure we should have
>> an unstable "API" being publicly documented like that.
>
> Yes please. I thought it was the API for the 3.6.X series. Just for
> the record, the doxygen  for the previous versions is available at
>
> http://octave.sourceforge.net/doxygen32/html/
> http://octave.sourceforge.net/doxygen34/html/

Okay, I actually checked in the Doxyfile into Savannah:

    http://hg.savannah.gnu.org/hgweb/octave/rev/e16080e36cf9

I suppose a journey of a thousand undocumented source files begins
with a Doxyfile.

Here is what this Doxyfile produces for the stable branch on my machine:

    http://jordi.platinum.linux.pl/tmp/oct-doxy/d6/d68/classoctave__base__value.html
    http://jordi.platinum.linux.pl/tmp/oct-doxy.zip

- Jordi G. H.

[Carnë Draug-4]

On 7 March 2013 21:37, Jordi Gutiérrez Hermoso <[hidden email]> wrote:

> On 7 March 2013 12:14, Carnë Draug <[hidden email]> wrote:
>> On 7 March 2013 17:00, Jordi Gutiérrez Hermoso <[hidden email]> wrote:
>>> On 7 March 2013 11:32, Carnë Draug <[hidden email]> wrote:
>>>> I have updated http://octave.sourceforge.net/doxygen/html/
>>>
>>> So that was doxygen output for 16201:743b895259e0. Perhaps I should
>>> generate it for the stable branch instead? I'm not sure we should have
>>> an unstable "API" being publicly documented like that.
>>
>> Yes please. I thought it was the API for the 3.6.X series.
>
> Here is what this Doxyfile produces for the stable branch on my machine:
>
>     http://jordi.platinum.linux.pl/tmp/oct-doxy/d6/d68/classoctave__base__value.html
>     http://jordi.platinum.linux.pl/tmp/oct-doxy.zip

Thank you. I have updated it on the forge website.

Carnë