Subject: [Fenics] Function order in programmer docs

From: "Garth N. Wells" <[email-masked]>
Date: Mon, 30 Aug 2010 14:14:27 +0100

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

---

From: Anders Logg <[email-masked]>
Date: Mon, 30 Aug 2010 15:18:04 +0200

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?

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.

--
Anders

---

From: "Garth N. Wells" <[email-masked]>
Date: Mon, 30 Aug 2010 14:24:54 +0100

> Any opinions on the order of functions? Alphabetical or as in the

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.

> Note punctuation on the first line. This is different from what we've

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

Garth

---

From: Kristian Ølgaard <[email-masked]>
Date: Mon, 30 Aug 2010 15:24:57 +0200

> Any opinions on the order of functions? Alphabetical or as in the

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.

> Note punctuation on the first line. This is different from what we've

I think comments in code should use punctuation like normal text, only
section headings like *Returns* should be without punctuation.

Kristian

> --
> Anders
>
> _______________________________________________
> Mailing list: https://launchpad.net/~fenics
> Post to     : [email-masked]
> Unsubscribe : https://launchpad.net/~fenics
> More help   : https://help.launchpad.net/ListHelp
>

---

From: Anders Logg <[email-masked]>
Date: Mon, 30 Aug 2010 15:35:37 +0200

> reason I started sorting the C++ functions too, to have similar

I have no firm opinion.

> section headings like *Returns* should be without punctuation.

Then the style guide needs to be updated. :-)

--
Anders

---

From: Anders Logg <[email-masked]>
Date: Mon, 30 Aug 2010 15:40:41 +0200

On Mon, Aug 30, 2010 at 02:24:54PM +0100, Garth N. Wells wrote:
> Definitely as ordered in the code - the function order in the code
> is not random, but hopefully well thought out.
>

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.

> 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

---

From: "Garth N. Wells" <[email-masked]>
Date: Mon, 30 Aug 2010 14:47:52 +0100

On 30/08/10 14:35, Anders Logg wrote:
>> On 30 August 2010 15:18, Anders Logg<[email-masked]>  wrote:

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

---

From: Kristian Ølgaard <[email-masked]>
Date: Mon, 30 Aug 2010 15:48:36 +0200

>> reason I started sorting the C++ functions too, to have similar

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.

> 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