|Re: [eigen] Proposal: documentation for Eigen3|
[ Thread Index |
| More lists.tuxfamily.org/eigen Archives
- To: eigen@xxxxxxxxxxxxxxxxxxx
- Subject: Re: [eigen] Proposal: documentation for Eigen3
- From: Benoit Jacob <jacob.benoit.1@xxxxxxxxx>
- Date: Sun, 6 Jun 2010 16:00:46 -0400
- Dkim-signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:received:received:in-reply-to :references:date:message-id:subject:from:to:content-type :content-transfer-encoding; bh=aSkXlYOTofBy5/9YXvG/Vqj8Ks7/x9FwWaFb/dMAvJE=; b=ZnVN9ZBHv513pJc/NcUsOQmPROgEiv1Qe4zUIzUTW9YKFLSBiY8jGbag5nuqk+KZOc mv32VsID0gUJsR1QAjra3VTVT35po2PfI6F7pCQgSgdQJcr29lPWZ4shx6Z6k/QLwtE5 F4KOxRvN1Ek0u17CobF4dYONLYcZhR0lEe6CU=
- Domainkey-signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :content-type:content-transfer-encoding; b=b5kAYDyziEGxZWbI4YdJJhwxn2eRnamEmWUSN5eDQIf87LEZpOv2b3gv+vguG3FCKa B9JWl7i8SNuDsOzM2CpaVK+pJdAbdBo+W7cu3NB45lEJ87iHbjD+MO8Ho4phikWXQGIZ NgC7WmiZKxVHFXOK/IxYvwX9NwzMxSXUkthuk=
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.
> On Sun, Jun 6, 2010 at 5:55 PM, Benoit Jacob <jacob.benoit.1@xxxxxxxxx>
>> 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
>> - 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.