Re: TexInfo -> Doxygen

[Søren Hauberg]

man, 24 01 2011 kl. 13:16 -0800, skrev Robert T. Short:
> I would actually be willing to work on this, but I always felt that 
> there was no real interest.  Maybe that is simply my misreading the 
> situation.

I think the problem is not lack of interest, but rather that we have no
clear picture of what we should document and how (level of detail)
things should be documented.

> Personally, I don't think software is complete without documentation.

I very much agree.

> 3.  Everyone that mucks about with a documented class has to agree to make
>       sure the documentation is up-to-date.  This is strongly influenced 
> by items
>       (1) and (2) - more work makes it less likely it will be done.  As 
> soon as
>       anybody fails in this task, the entire effort becomes wasted.

Would it be reasonable to have some standard way of indicating the a
piece of documentation is out-dated? That way, if somebody needs to
change the way a class works, but doesn't have the time (or is simply to
lazy) to write proper documentation, other people would at least know
that the docs were outdated. This could also help other people identify
places where a documentation contribution would be welcome. This might
be a silly idea as we could easily end up with nothing but out-dated
documentation, but I thought I'd bring it up anyway.

> Some really valuable things that would come out of this effort though.  
> First, I find UML (or SDL, take your pick) structure diagrams quite 
> valuable, both in the design of complex systems and in understanding 
> existing systems.  For some of the more complex subsystems, some action 
> diagrams would be extremely valuable as well.  A further benefit is that 
> pictures often expose design or concept flaws (and points out the GOOD 
> things).

Just having visual class hierarchies is a great help to me. I, at least,
use those from the Octave-Forge website fairly often.

Søren