fenics team mailing list archive

[Anders Logg <logg@xxxxxxxxx>]

On Mon, Aug 30, 2010 at 02:24:54PM +0100, Garth N. Wells wrote:
>
>
> On 30/08/10 14:18, Anders Logg 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?
> >
>
> Definitely as ordered in the code - the function order in the code
> is not random, but hopefully well thought out.
>
> Also, do we want private functions and data documented? If yes, it
> should be made clear that a function/data is private.

I think we can do without that, especially since this is already
handled by putting /// in front of public functions and // in front of
private functions.

> >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.
> >
>
> Can the number of indentations in the generated doc be reduced? I
> find it disturbing.  For example, could 'Connectivity' appear
> directly below 'An array of ...'

It makes more sense if you look at examples that list more than one
thing, but in this case (for return values) I guess we will always
return just one thing.

And here the extra line can even be removed. The information contained
in it should already be in the first line:

  /// Get connectitivity for all cells.
  ///
  /// *Returns*
  ///     An array of integers

In addition, this particular function should be explained more
carefully. It's not really clear what it does. In fact, it's there
specifically to be used by the Python layer.


--
Anders