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<[email protected]> 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
_______________________________________________
Mailing list: https://launchpad.net/~fenics
Post to : [email protected]
Unsubscribe : https://launchpad.net/~fenics
More help : https://help.launchpad.net/ListHelp
