fenics team mailing list archive

[Kristian Ølgaard <k.b.oelgaard@xxxxxxxxx>]

On 30 August 2010 15:35, Anders Logg <logg@xxxxxxxxx> 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.

I don't have I strong opinion either, I just like when things look the
same, but users who only use one interface wouldn't know anyway.

>> > 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. :-)

Very likely, but we'll have to do that anyway once we figured out if
functions should be sorted or not.
I think the missing punctuation above stems from the *Arguments*,
where it would look rather silly to have:
*Arguments*
  point.
    A _Point_ class

instead of 'point' without '.'.

Kristian


> --
> Anders
>