Re: [Toon-members] TooN/doc Doxyfile documentation.h matrixdoc.h v...

[Gerhard Reitmayr]

Hi,

I am wondering, wouldn't it make sense to move documentation into the  
actual header files, where ever possible ?

I understand that for Vector and Matrix, this doesn't make much sense,  
but for everything else (such as groups, decompositions, helpers. etc)  
it would simplify maintenance and access to the information a lot (for  
people like me who look at header files for info )

what do you think ?

cheers,
  Gerhard

On 14 Apr 2009, at 08:12, Tom Drummond wrote:

> CVSROOT:        /cvsroot/toon
> Module name:    TooN
> Changes by:     Tom Drummond <twd20>      09/04/14 07:12:37
>
> Modified files:
>         doc            : Doxyfile documentation.h matrixdoc.h
>                          vectordoc.h
>
> Log message:
>         documentation polishing
>
> CVSWeb URLs:
> http://cvs.savannah.gnu.org/viewcvs/TooN/doc/Doxyfile?cvsroot=toon&r1=1.4&r2=1.5
> http://cvs.savannah.gnu.org/viewcvs/TooN/doc/documentation.h?cvsroot=toon&r1=1.14&r2=1.15
> http://cvs.savannah.gnu.org/viewcvs/TooN/doc/matrixdoc.h?cvsroot=toon&r1=1.8&r2=1.9
> http://cvs.savannah.gnu.org/viewcvs/TooN/doc/vectordoc.h?cvsroot=toon&r1=1.9&r2=1.10
>
> Patches:
> Index: Doxyfile
> ===================================================================
> RCS file: /cvsroot/toon/TooN/doc/Doxyfile,v
> retrieving revision 1.4
> retrieving revision 1.5
> diff -u -b -r1.4 -r1.5
> --- Doxyfile    27 Mar 2009 21:03:09 -0000      1.4
> +++ Doxyfile    14 Apr 2009 07:12:37 -0000      1.5
> @@ -23,7 +23,7 @@
> # This could be handy for archiving the generated documentation or
> # if some version control system is used.
>
> -PROJECT_NUMBER         = 1.0.5
> +PROJECT_NUMBER         = 2.0.0
>
> # The OUTPUT_DIRECTORY tag is used to specify the (relative or  
> absolute)
> # base path where the generated documentation will be put.
>
> Index: documentation.h
> ===================================================================
> RCS file: /cvsroot/toon/TooN/doc/documentation.h,v
> retrieving revision 1.14
> retrieving revision 1.15
> diff -u -b -r1.14 -r1.15
> --- documentation.h     14 Apr 2009 06:45:57 -0000      1.14
> +++ documentation.h     14 Apr 2009 07:12:37 -0000      1.15
> @@ -488,8 +488,8 @@
> the transpose can be used as an l-value so <code>M1 = M2.T();</code>  
> and
> <code>M1.T() = M2;</code> do exactly the same thing.
>
> -This also means that <code>M = M.T();</code> does the wrong thing.   
> However, since .T()
> -essentially costs nothing, it should be very rare that you need to  
> do this.
> +<b> Warning: This also means that <code>M = M.T();</code> does the  
> wrong thing.</b>
> +However, since .T() essentially costs nothing, it should be very  
> rare that you need to do this.
>
> \subsubsection ssDynamic Dynamic sized vectors and matrices
>
>
> Index: matrixdoc.h
> ===================================================================
> RCS file: /cvsroot/toon/TooN/doc/matrixdoc.h,v
> retrieving revision 1.8
> retrieving revision 1.9
> diff -u -b -r1.8 -r1.9
> --- matrixdoc.h 11 Mar 2007 21:26:35 -0000      1.8
> +++ matrixdoc.h 14 Apr 2009 07:12:37 -0000      1.9
> @@ -87,7 +87,9 @@
>   // ...
> }
> @endcode
> -<code>Matrix<></endcode> is a synonym for <code>Matrix<-1,-1></ 
> endcode>
> +
> +<code>Matrix<></code> is a synonym for <code> Matrix<Dynamic,  
> Dynamic> </code> which is
> +<code>%Matrix<-1,-1></code>
>
> \par Row-major and column-major
>
> @@ -100,9 +102,10 @@
> You can override the default for a specific matrix by specifying the  
> layout when
> you construct it:
> @code
> -Matrix<3,3,ColMajor> M1;
> -Matrix<-1,-1,RowMajor> M2(nrows, ncols);
> +Matrix<3,3,double,ColMajor> M1;
> +Matrix<-1,-1,double,RowMajor> M2(nrows, ncols);
> @endcode
> +In this case the precision template argument must be given as it  
> precedes the layout argument
>
> @ingroup gLinAlg
> **/
>
> Index: vectordoc.h
> ===================================================================
> RCS file: /cvsroot/toon/TooN/doc/vectordoc.h,v
> retrieving revision 1.9
> retrieving revision 1.10
> diff -u -b -r1.9 -r1.10
> --- vectordoc.h 2 Apr 2009 03:56:38 -0000       1.9
> +++ vectordoc.h 14 Apr 2009 07:12:37 -0000      1.10
> @@ -26,7 +26,7 @@
> {
>
> 	/// A symbolic constant used as the size argument for dynamically  
> sized vectors and matrices
> -       const int Dynamic=1;
> +       const int Dynamic=-1;
>
> 	/// A series of overloaded functions to create a Vector from a list  
> of numbers. See the detailed documentation
>         /// for Vector for information on usage.
>
>
> _______________________________________________
> Toon-members mailing list
> address@hidden
> http://lists.nongnu.org/mailman/listinfo/toon-members

--
Gerhard Reitmayr
MIL, Engineering Department, Cambridge University
http://mi.eng.cam.ac.uk/~gr281/