fenics team mailing list archive

["Garth N. Wells" <gnw20@xxxxxxxxx>]

On 30/08/10 14:35, Anders Logg wrote:
> On Mon, Aug 30, 2010 at 03:24:57PM +0200, Kristian Ølgaard wrote:
> > On 30 August 2010 15:18, Anders Logg<logg@xxxxxxxxx>  wrote:
> > > On Mon, Aug 30, 2010 at 02:14:27PM +0100, Garth N. Wells wrote:
> > > > Is it deliberate that the function order in the programmer docs
> > > > differs from the order in which functions are declared in the .h
> > > > files?
> > > >
> > > > Garth
> > >
> > > Yes. It's alphabetical in the documentation. It can easily be turned
> > > off, just need to comment out the line that calls sort().
> > >
> > > Any opinions on the order of functions? Alphabetical or as in the
> > > code?
> >
> > I think it is easier to find a function if they are listed
> > alphabetically. The Python autodoc will sort the functions
> > automatically, I don't know if it can be switched off. This is the
> > reason I started sorting the C++ functions too, to have similar
> > looking docs.
>
> I have no firm opinion.

Similar functions should be grouped together. The main reason for 
turning to a programmers reference is to find out what member functions 
are available, which is why the most important/used functions come 
first, and similar functions are grouped. An index should be used for an 
alphabetical listing.

I use the Trilinos programmer docs to figure out how to use it, and I 
doubt that I could have made any sense out of it if it used alphabetical 
ordering. For example, the two functions Epetra functions

  InsertMyValues
  ReplaceMyValues

would appear at opposite ends of the doc with alphabetical ordering, 
rather than together.

Garth

> > > Another thing to discuss is the style of documentation. Mesh.h
> > > currently does
> > >
> > >   /// Get cell connectivity.
> > >   ///
> > >   /// *Returns*
> > >   ///     An array of integers
> > >   ///         Connectivity for all cells.
> > >   ///
> > >
> > > Note punctuation on the first line. This is different from what we've
> > > done before.
> >
> > I think comments in code should use punctuation like normal text, only
> > section headings like *Returns* should be without punctuation.
>
> Then the style guide needs to be updated. :-)
>
> --
> Anders