[Developers] Describing APIs in the Cactus documentation

[Jonathan Thornburg]

On Sat, 7 May 2005, Erik Schnetter wrote:
> The APIs in the Cactus documentation are currently described in a way
> that seems a bit awkward.  Here is an example for a C routine:
>
> int status = CCTK_GroupbboxVI(const cGH *cctkGH,
>                              int dim,
>                              int *bbox,
>                              int varindex);
[[...]]
>
> If we can agree on this, then I would suggest to explain both C and
> Fortran routines by their declaration.  We should mention this decision
> somewhere in a comment the latex sources.  We don't need to switch over
> all declarations at once -- there are many things that still need to be
> switched over -- but new descriptions should be done in this way.
>
> This would look as follows for C:
[[...]]


> int CCTK_GroupbboxVI(const cGH *cctkGH,
>                     int dim,
>                     int *bbox,
>                     int varindex);

I don't like this format, and would prefer to keep the current one,
because it provides additional information, namely an indication of
what the returned result *means*.

That is, for example, I find the distinction between
   int status = CCTK_Blah(int foo, int bar)
and
   int handle = CCTK_Blah(int foo, int bar)
and
   int varindex = CCTK_Blah(int foo, int bar)
and
   int group_index = CCTK_Blah(int foo, int bar)
to be a useful one, and I would like to preserve this in the prototype.

I realise we have a "Result" section, where the semantics of the result
should be explained in detail, but I think explicitly naming the result
in the prototype provides a useful additional cue.


[As Erik quite accurately notes, the current descriptions aren't valid
function declarations.  But I don't see that as a problem: if you want
a valid function declaration, grep src/include/*.h!  In any case, valid
function declarations are needed to communicate with *compilers*, while
documentation is supposed to communicate information to *humans*.]


I have no strong feelings either way about the proposed change to
Fortran descriptions.


>
> #include "cctk.h"

I like this part!  The name(s) of the header file(s) to be #included
is/are essential information for the programmer trying to use the function,
and I think it's unfortunate that some Cactus Reference Manual entries
omit this.  (If it were _always_ "cctk.h and nothing else" then it could
perhaps be omitted but it's not _always_ that.)

ciao,

-- 
-- Jonathan Thornburg <jthorn at aei.mpg.de>
    Max-Planck-Institut fuer Gravitationsphysik (Albert-Einstein-Institut),
    Golm, Germany, "Old Europe"     http://www.aei.mpg.de/~jthorn/home.html
    "Washing one's hands of the conflict between the powerful and the
     powerless means to side with the powerful, not to be neutral."
                                       -- quote by Freire / poster by Oxfam