[Developers] Describing APIs in the Cactus documentation

[Erik Schnetter]

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);

Note that this is neither a declaration nor a call, it is a strange 
mixture of both.  Unix man pages document routines by giving their 
declaration (i.e. without the "status =" part).

For Fortran we do the same:

call CCTK_GroupbboxVI(status, cctkGH, dim, bbox, varindex)

integer       status
CCTK_POINTER  cctkGH
integer       dim
integer       bbox(dim)
integer       varindex
character*(*) varname

This is again a mixture between a call statement and a declaration.



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:

#include "cctk.h"
int CCTK_GroupbboxVI(const cGH *cctkGH,
                     int dim,
                     int *bbox,
                     int varindex);

And for Fortran:

#include "cctk.h"
subroutine CCTK_GroupbboxVI(status, cctkGH, dim, bbox, varindex)
   integer       status
   CCTK_POINTER  cctkGH
   integer       dim
   integer       bbox(dim)
   integer       varindex
   character*(*) varname
end subroutine

This might look strange to people who don't know Fortran 90, but this is 
actually a legal interface declaration.  We can, if we so desire, put 
"interface" and "end interface" around this.  We can also add an 
"implicit none" statement.  But these are all boilerplate and not 
necessary.

Giving the argument types is more important for Fortran than for C 
because Fortran does not convert routine arguments automatically as C 
does.  Wrong argument types, if detected, lead to errors, and lead to 
crashes if undetected.

Because Fortran passes all arguments by reference, it is necessary to 
describe which arguments need to be defined before the routine is 
called and which arguments are changed by the routine.  This 
information can unfortunately not be expressed in the interface, and 
therefore has to be given in the explanation of the arguments.  
(Fortran's intent declarations have a slightly different meaning and 
must probably be omitted here.  "Probably" because this depends on the 
Fortran/C inter language calling conventions, which are compiler 
dependent.)

-erik

-- 
Erik Schnetter <schnetter at aei.mpg.de>   http://www.aei.mpg.de/~eschnett/

My email is as private as my paper mail.  I therefore support encrypting
and signing email messages.  Get my PGP key from www.keyserver.net.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://www.cactuscode.org/pipermail/developers/attachments/20050507/1abc9356/attachment-0002.bin