Re: Doxygen documentation

[Robert T. Short]

Soren 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?
>
> Soren
>
> 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