[eigen] Documenting functions which return an Matrix

[Dale Lukas Peterson <hazelnusse@xxxxxxxxx>]

I have some functions which need to return Matrices of specific sizes
and I would like clients of the class to see at a glance what size
those matrices are.  I have been doing things like:

Matrix<double, 3, 6, RowMajor> my_func();

then in client code:

a = my_func();

The reason I am declaring the function this way is primarily so users
who see it know what size matrix they are getting back.  Is this the
preferred way to do this?

Some of my matrices are small (3x3), and some are bigger (20x20).
Inside of my_func(), I typically declare a matrix on the heap to do
the necessary calculations and populate the matrix, and then return
it.  I am fine with all things being on the heap, but it would be nice
to know that I'm not copying things unnecessarily because of the way
I've declared the function.

I realize I can require clients to pass a const reference to a Matrix
of their choosing (Dynamic or Fixed) as a function parameter, rather
than using return, but the syntax of operator= is nicer and I don't
really want to give up that syntax.

1) How do people document their functions that return matrices of
known size, even if those matrices are allocated on the heap?

2) I see four cases that I'm not 100% clear on what happens when I do
something like a = my_func():

a) a is a dynamic sized Matrix and my_func returns a fixed size Matrix.
b) a is a dynamic sized Matrix and my_func returns a dynamic size Matrix.
c) a is a fixed sized Matrix and my_func returns a fixed size Matrix.
d) a is a fixed sized Matrix and my_func returns a dynamic size Matrix.

Can anybody clarify this for me and give me recommendations on how to
make it clear to users what the size of the matrices are without
shooting myself in the foot?

Thanks,
Luke