Re: [eigen] docs updates

[Benoît Jacob <jacob@xxxxxxxxxxxxxxx>]

On Sunday 12 October 2008 16:06:25 Scott Wheeler wrote:
> Benoît Jacob wrote:
> > Indeed, there is no default value. I'll update the docs to mention that
> > you can use the special value Eigen::Dynamic.
>
> Already did.  In bold.  :-)

Somehow I didn't receive your commit msg for 869826. I suppose this is because 
of the recent svn server problems.

I'll proof-read your reworked Matrix documentation, here are already a few 
comments:

"or \em dynamically by specifying \em Dynamic as the size."

Here "size" is not precise enough, I'd say "as size template parameters".

***

\param _Scalar Numeric type, i.e. float, double, int

Here I prefered the old version which said:

\param _Scalar the scalar type, i.e. the type of the coefficients

however I understand that it's a good idea to give an example 'float' but if 
you give the three types as above and says "i.e." it suggests these are the 
only types allowed. So I'd go for

\param _Scalar the scalar type, i.e. the type of the coefficients, for example 
\c float.

***

  * \param _Rows Numer of rows, or \b Dynamic
  * \param _Cols Number of columnss, or \b Dynamic

typos :)

Moreover, why did you change this? The old version said basically the same, 
with more words. Did you feel it was important to have very short 
descriptions here and the old version was too wordy?

For reference:

* \param _Rows the number of rows at compile-time. Use the special value \a 
Dynamic to specify that the number of rows is dynamic, i.e. is not fixed at 
compile-time.
* \param _Cols the number of columns at compile-time. Use the special value \a 
Dynamic to specify that the number of columns is dynamic, i.e. is not fixed 
at compile-time.

Wasn't this more helpful ?

***

"Dynamic matrices <em>do not</em> expand dynamically."

what do you mean?



> if(p == 2)
> {
>     // do it the fast way
> }
> else
> {
>     // do it the general way
> }

If p is a compile-time constant then the user may as well call other 
convenience functions such as l1Norm() etc; if p is not, then we are probably 
in the general case. I am reluctant to write code as above as it could easily 
generate binary code for all paths. If such a form were really needed i'd 
rather make p a template parameter and use a meta-selector so only one path 
gets compiled.


---