[eigen] Proposal: documentation for Eigen3

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

Hi,

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

*** Why that doesn't work anymore ***

Two main reasons, A and B:

A. We have a much bigger class hierarchy now, basically:

EigenBase<--DenseCoeffsBase<--DenseBase<--MatrixBase or
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:

EigenBase<--DenseCoeffsBase<--DenseBase<--MatrixBase or
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
class docs.

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

I think that the new Doxygen pages that we need to write, fall into
some categories:

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

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:
http://eigen.tuxfamily.org/dox/TopicLazyEvaluation.html
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
head:

  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
compilation error).

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

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

Do you like this proposal?

Cheers,
Benoit