Re: [eigen] Proposal: documentation for Eigen3

[Benoit Jacob <jacob.benoit.1@xxxxxxxxx>]

2010/6/6 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.

Ah yes, right! I totally forgot to mention that.

Benoit

>
> 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.
>