Re: [eigen] Proposal: documentation for Eigen3

[Gael Guennebaud <gael.guennebaud@xxxxxxxxx>]

I totally agree with that. For me, the main advantage of doxygen is that it is tightly coupled with the source (automatic cross ref + syncing/versioning). But of course if someone prefers to start documenting a specific topic on the wiki, then he/she is much welcome :)

Also I'd like to emphasize that thanks to Thomas the doxygen doc is automatically updated on the web site each day. That means each documentation change is immediately and easily available to everybody. Another argument that I've not seen mentioned by Benoit (surprisingly) is that doxygen easily allows us to include C++ examples which are compiled (validated) by the compiler and to include their true outputs.

gael

On Sun, Jun 6, 2010 at 5:55 PM, Benoit Jacob <jacob.benoit.1@xxxxxxxxx> wrote:

OK, so, I agree that there is a use for documentation on both the wiki
and doxygen... which is actually what we are doing right now! Perhaps
all what was needed, was a good clarification of what should go into
doxygen, and what should go into the wiki. It's going to be impossible
to dictate absolute hard rules, but here are some thoughts:
 - The doxygen docs are automatically versioned, the wiki isn't, so
wiki pages must be careful to say to which version of Eigen they
refer.
 - Standard tutorials and API docs should go into doxygen
 - Topic-specific pages on the most important/general topics (e.g.
lazy evaluation) should go into doxygen
 - Everyone is welcome to create Wiki pages on topics that doxygen
overlooks (e.g. how to use Eigen with compiler X or interplay with
library Y or numeric type Z...). It is possible/easy to later convert
them into doxygen pages, if needed.