Doxygen documentation

[Søren Hauberg]

Hi All

We're in the process of changing the Octave-Forge website to allow for a
different release procedure. The current test-version of the website is
available at

  http://octave.sf.net/test

One issue about the webpage that is being discussed is if we should host
Doxygen generated documentation on this webpage (as we are doing now).
The argument against having this on octave.sf.net is that such
documentation is about core Octave and not about the packages.

So, I'd like to ask if we should host Doxygen generated documentation on
www.octave.org instead? The argument against having this on
www.octave.org is that it might give the impression that the C++ API is
stable.

Any thoughts on this?

Søren

P.S. Most of the stuff on the new webpage is auto-generated and the code
for this should scale to other websites. So, it could be used for
www.octave.org as well.

[Robert T. Short]

Søren Hauberg wrote:

> Hi All
>
> We're in the process of changing the Octave-Forge website to allow for a
> different release procedure. The current test-version of the website is
> available at
>
>   http://octave.sf.net/test
>
> One issue about the webpage that is being discussed is if we should host
> Doxygen generated documentation on this webpage (as we are doing now).
> The argument against having this on octave.sf.net is that such
> documentation is about core Octave and not about the packages.
>
> So, I'd like to ask if we should host Doxygen generated documentation on
> www.octave.org instead? The argument against having this on
> www.octave.org is that it might give the impression that the C++ API is
> stable.
>
> Any thoughts on this?
>
> Søren
>
> P.S. Most of the stuff on the new webpage is auto-generated and the code
> for this should scale to other websites. So, it could be used for
> www.octave.org as well.
>
>
>
>  

I can't see how the stability argument is any argument at all.  Open
source code is rarely very stable and backwards compatibility is seldom
a design goal.  I personally think well in pictures and the results from
doxygen are helpful.

Personally, I think we should include doxygen markup in all the octave
sources.  I realize it is a lot of work, but worth it.  I have said
before that the biggest obstacle to newbies making real contributions to
the octave core is the enormous learning curve involved in understanding
the sources.  I really think the number of people that understand the
sources is so small as to be frightening.  If JWE and Jaroslav were to
suddenly be unavailable, I fear that octave development would be
crippled, possibly beyond recovery.

I guess I should clarify - I don't care WHAT markup we use, but doxygen
seems to be the de facto standard.

Bob