fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

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.

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