|[eigen] Proposal: documentation for Eigen3|
[ Thread Index |
| More lists.tuxfamily.org/eigen Archives
- To: eigen <eigen@xxxxxxxxxxxxxxxxxxx>
- Subject: [eigen] Proposal: documentation for Eigen3
- From: Benoit Jacob <jacob.benoit.1@xxxxxxxxx>
- Date: Sat, 5 Jun 2010 09:56:42 -0400
- Dkim-signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:received:received:date:message-id :subject:from:to:content-type; bh=AREyMVNs+1YevjlwCTYld3u44LHoWZQiAV6qzJ8Jciw=; b=VqNGtl3mb2pZpK/C2UFtsQ1QxzQLdasitk7R6Q9gs9rixGWiv9xHjdRQdlviFu6Gmy 2xwIupao3QB525JmpdyWdNMFCiNGWQ1opz5jBNO1FcMv5SJDEP/lO3yMB2bkLMcRzJ2D 0rd43VsNvjLBSxO0kapeoqDh+P4rU3ax3FtAU=
- Domainkey-signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:date:message-id:subject:from:to:content-type; b=Fgdzn0Ipc+p+HS497Fv9IoZ9M4HsLt3RhnuHBThzCgYZe7XpvjxOjuA+DcHRAkgxgi eaAaC2sipo8ZXsJF7zZWsopbuBEqpbyWHjGR74QM4Vv7Vo/Asehg/4TKuQKa6i6zlWQL 8WrM+Q1n8qFZ1RWkGYZtFyBUZe28BTrR04tME=
It's time we start a big documentation push for Eigen3: indeed it's
starting to be one of the key factors holding back the beta cycle.
Here's IMO why we've been kind of paralyzed on the documentation
front, lately: our documentation design still is the one from Eigen2,
and Eigen3 breaks its basic assumptions.
Eigen2's documentation was: 90% just Doxygen-generated class dox, and
then some tutorial to help initially walk through it. We were able to
say "essentially all of the dox is in class MatrixBase, have a look
*** Why that doesn't work anymore ***
Two main reasons, A and B:
A. We have a much bigger class hierarchy now, basically:
ArrayBase<--(The Expression Type)
And the API is distributed over all these levels! Some in DenseBase,
some in MatrixBase, ...
For plain matrices/vectors it's even worse:
ArrayBase<--DenseStorageBase<--Matrix or Array
Worst of all, the inheritance diagram itself depends on
meta-programming, so in many cases Doxygen simply can't understand it.
B. We now have a bigger set of "basic concepts". Most importantly the
new Array concept (as opposed to Matrix). This requires a bigger
"tutorial" part, as opposed to just telling people to look at doxygen
*** Proposal going forward ***
Of course we keep using Doxygen, but we don't just let people look at
auto-generated class docs anymore. We write a LOT more tutorial-like
Doxygen pages, and from there we link to doxygen-generated pages, and
we also link to anchors in these pages corresponding to methods. While
class documentation is often intimidating, method documentation is
I think that the new Doxygen pages that we need to write, fall into
1) a super quick 5-minute "getting started" tutorial, similar to the
beginning of our existing tutorial.
2) a long, detailed 1-hour tutorial, taking the time to explain some
basic concepts: Matrix vs. Array, Dynamic-size vs. Fixed-size. That's
4 combinations already, and I think that such a tutorial should give
some example for these 4 cases. That would already be a multi-page
tutorial. Perhaps 4-8 pages and a target reading time of 1 hour.
3) a set of topical "cheat sheets", basically like most of current
tutorial, just updated, and freed from the requirement of being
actually a tutorial - this just has to be a reference, since the
tutorial role is taken over by other pages. Also see ASCII quick
Note: I think that for the 1st beta, it's enough to do 1) and 2), and
start 3) (at least update the existing tables).
4) we need a bunch of doxygen pages on specific topics. Not a
requirement for the 1st beta, of course. In Eigen2 we pretty much had
only one, on Lazy Evalutation:
We need more of these pages. They can even overlap a little bit with
each other, the goal is to make info easy to find. From the top of my
a) what member data is inside of a Matrix/Array? What's the memory
layout? Is it heap allocated? People want to know how to interact with
other libs, and want to know if Eigen incurs any memory overhead (esp.
in the fixed-size case). Knowing that a Matrix is just a dumb array of
coeffs, will also help people understand stuff.
b) a page more generally on Storage Orders. What's the default? How
to use row-major? How to set it as the default? When evaluating
m.transpose(), what storage order is used? What about the special case
of Vectors, can a row-vector be column-major storage order (hint: no
it can't, vectors MUST have the "right" storage order or you get a
c) a page on memory allocation, even if that will overlap with many
other pages, because many people will be looking for info about that.
What causes heap allocation? Mention aligned malloc too. That page
should perhaps be mostly just links to other pages.
d) a page on Sizes at compile time. The constant Dynamic. The
Max-sizes. The link between the Max-sizes and memory allocation: the
fact that Matrix4f().block(...).eval() doesn't cause a heap
allocation. Block(...) is the perfect example for the Max-sizes.
e) a page about alignment, aligned malloc, alignment qualifiers, the
issues that that can cause (link to the unaligned assert's pages)
f) a page explaining generally what expression templates are, lazy
g) a page about aliasing, eval(), noalias().
h) each non-Core module needs its own dox page.
etc, etc... the list will keep growing. Fortunately, 4) is not a
Do you like this proposal?