Point out that CCTK_Equals() should be used to check STRING and KEYWORD

parameters. This closes PR Cactus-198.
Also fixed some places where 'cGH *' turned into 'const cGH *'.


git-svn-id: http://svn.cactuscode.org/flesh/trunk@2539 17b73243-c579-4c4c-a9d2-2d5706c11dac

1 files changed, 30 insertions, 32 deletions

diff --git a/doc/UsersGuide/FunctionReference.tex b/doc/UsersGuide/FunctionReference.tex
index da07141f..48d7a7bc 100644
--- a/doc/UsersGuide/FunctionReference.tex
+++ b/doc/UsersGuide/FunctionReference.tex
@@ -170,7 +170,7 @@ from Fortran.
 
 \item[CCTK\_Equals] 
   [\pageref{CCTK-Equals}] 
-  Check for equality of strings
+  Check a STRING or KEYWORD parameter for equality equality with a given string
 
 \item[CCTK\_Exit]
   [\pageref{CCTK-Equals}] 
@@ -480,7 +480,7 @@ from Fortran.
 \begin{CCTKFunc}{CCTK\_ArrayGroupSize}{}
 \label{CCTK-ArrayGroupSize}
 \subroutine{int *}{}{size}
-\argument{cGH *}{}{cctkGH}
+\argument{const cGH *}{}{cctkGH}
 \argument{const char *}{}{groupname}
 \showcargs
 \begin{params}
@@ -501,7 +501,7 @@ from Fortran.
 \begin{CCTKFunc}{CCTK\_ArrayGroupSizeB}{}
 \label{CCTK-ArrayGroupSizeB}
 \subroutine{int *}{}{size}
-\argument{cGH *}{}{cctkGH}
+\argument{const cGH *}{}{cctkGH}
 \argument{int}{}{groupindex}
 \argument{int}{}{dir}
 \argument{const char *}{}{groupname}
@@ -524,7 +524,7 @@ from Fortran.
 \begin{CCTKFunc}{CCTK\_ArrayGroupSizeI}{}
 \label{CCTK-ArrayGroupSizeI}
 \subroutine{int *}{}{size}
-\argument{cGH *}{}{cctkGH}
+\argument{const cGH *}{}{cctkGH}
 \argument{int}{}{dir}
 \argument{int}{}{index}
 \showargs
@@ -975,7 +975,7 @@ will be used if the coordinate direction is given as less than or equal to zero,
 \begin{CCTKFunc}{CCTK\_CoordRange}{Return the global upper and lower bounds for a given coordinate}
 \label{CCTK-CoordRange}
 \subroutine{int}{integer}{ierr}
-\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{const cGH *}{CCTK\_POINTER}{cctkGH}
 \argument{CCTK\_REAL}{CCTK\_REAL}{lower}
 \argument{CCTK\_REAL}{CCTK\_REAL}{upper}
 \argument{int}{integer}{direction}
@@ -1051,7 +1051,7 @@ using {\tt CCTK\_CoordRegisterSystem}.
 values of a coordinate on a given grid hierachy}
 \label{CCTK-CoordRegisterRange}
 \subroutine{int}{integer}{ierr}
-\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{const cGH *}{CCTK\_POINTER}{cctkGH}
 \argument{CCTK\_REAL}{CCTK\_REAL}{min}
 \argument{CCTK\_REAL}{CCTK\_REAL}{max}
 \argument{int}{integer}{direction}
@@ -1346,28 +1346,26 @@ the Cactus scheduler via a thorn's {\tt schedule.ccl} file.
 
 
 % CommOverloadables.c
-\begin{CCTKFunc}{CCTK\_Equals}{Check for string equality}
+\begin{CCTKFunc}{CCTK\_Equals}{Checks a STRING or KEYWORD parameter for equality with a given string}
 \label{CCTK-Equals}
 \function{int}{integer}{istat}
-\argument{const char *}{character*(*)}{string1}
-\argument{const char *}{character*(*)}{string2}
+\argument{const char *}{CCTK\_POINTER}{param}
+\argument{const char *}{character*(*)}{value}
 \showargs
 \begin{params}
 \parameter{istat}{returns success or failure of equality}
-\parameter{string1}{first string to be compared}
-\parameter{string2}{second string to be compared}
+\parameter{param}{the STRING or KEYWORD parameter to check}
+\parameter{value}{the string value to compare against}
 \end{params}
 \begin{discussion}
-This function compares a Cactus parameter with a string, and performs a 
-case-independent comparison, returning one if the strings are the same, 
-and zero if they differ. 
+This function compares a Cactus parameter of type STRING or KEYWORD against a
+given string value. The comparison is performed case-independent,
+returning a non-zero value if the strings are the same, and zero if they differ.
+
+Note that in Fortran code, STRING or KEYWORD parameters are passed as C pointers,
+and can not be treated as normal Fortran strings. Thus {\t CCTK\_Equals()}
+should be used to check the value of such a parameter.
 \end{discussion}
-\begin{examples}
-\begin{tabular}{@{}p{3cm}cp{11cm}}
-\end{tabular}
-\end{examples}
-\begin{errorcodes}
-\end{errorcodes}
 \end{CCTKFunc}
 
 % CommOverloadables.c
@@ -2600,7 +2598,7 @@ A negative return code indicates an error condition:
 \begin{CCTKFunc}{CCTK\_MyProc}{Returns the number of the local processor for a parallel run}
 \label{CCTK-MyProc}
 \function{int}{integer}{myproc}
-\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{const cGH *}{CCTK\_POINTER}{cctkGH}
 \showargs
 \begin{params}
 \parameter{cctkGH}{pointer to CCTK grid hierarchy}
@@ -2655,7 +2653,7 @@ and not the active thorn list.
 \begin{CCTKFunc}{CCTK\_nProcs}{Returns the number of processors being used for a parallel run}
 \label{CCTK-nProcs}
 \function{int}{integer}{nprocs}
-\argument{cGH *}{CCTK\_POINTER}{cctkGH}
+\argument{const cGH *}{CCTK\_POINTER}{cctkGH}
 \showargs
 \begin{params}
 \parameter{cctkGH}{pointer to CCTK grid hierarchy}
@@ -3172,7 +3170,7 @@ checked.
 \begin{CCTKFunc}{CCTK\_QueryGroupStorage}{}
 \label{CCTK-QueryGroupStorage}
 \subroutine{int}{}{storage}
-\argument{cGH *}{}{cctkGH}
+\argument{const cGH *}{}{cctkGH}
 \argument{const char *}{}{groupname}
 \showcargs
 \begin{params}
@@ -3193,7 +3191,7 @@ checked.
 \begin{CCTKFunc}{CCTK\_QueryGroupStorageI}{}
 \label{CCTK-QueryGroupStorageI}
 \subroutine{int}{}{storage}
-\argument{cGH *}{}{cctkGH}
+\argument{const cGH *}{}{cctkGH}
 \argument{int}{}{groupindex}
 \showcargs
 \begin{params}
@@ -3214,7 +3212,7 @@ checked.
 \begin{CCTKFunc}{CCTK\_QueryGroupStorageB}{}
 \label{CCTK-QueryGroupStorageB}
 \subroutine{int}{}{storage}
-\argument{cGH *}{}{cctkGH}
+\argument{const cGH *}{}{cctkGH}
 \argument{int}{}{groupindex}
 \argument{const char *}{}{groupname}
 \showcargs
@@ -3292,7 +3290,7 @@ IO methods should be registered at {\t CCTK\_STARTUP}.
 \label{CCTK-RegisterIOMethodOutputGH}
 \function{int}{integer}{istat}
 \argument{int}{}{handle}
-\argument{int}{}{(* func)(cGH *)}
+\argument{int}{}{(* func)(const cGH *)}
 \showcargs
 \begin{params}
 \end{params}
@@ -3313,7 +3311,7 @@ IO methods should be registered at {\t CCTK\_STARTUP}.
 \label{CCTK-RegisterIOMethodTimeToOutput}
 \function{int}{integer}{istat}
 \argument{int}{}{handle}
-\argument{int}{}{(* func)(cGH *,int)}
+\argument{int}{}{(* func)(const cGH *,int)}
 \showcargs
 \begin{params}
 \end{params}
@@ -3333,7 +3331,7 @@ IO methods should be registered at {\t CCTK\_STARTUP}.
 \label{CCTK-RegisterIOMethodTriggerOutput}
 \function{int}{integer}{istat}
 \argument{int}{}{handle}
-\argument{int}{}{(* func)(cGH *,int)}
+\argument{int}{}{(* func)(const cGH *,int)}
 \showcargs
 \begin{params}
 \end{params}
@@ -3353,7 +3351,7 @@ IO methods should be registered at {\t CCTK\_STARTUP}.
 \label{CCTK-RegisterIOMethodOutputVarAs}
 \function{int}{integer}{istat}
 \argument{int}{}{handle}
-\argument{int}{}{(* func)(cGH *,const char*, const char *)}
+\argument{int}{}{(* func)(const cGH *,const char*, const char *)}
 \showcargs
 \begin{params}
 \end{params}
@@ -3547,7 +3545,7 @@ the preferred method from synchronising variables.
 \begin{CCTKFunc}{CCTK\_VarDataPtr}{Returns the data pointer for a grid variable}
 \label{CCTK-VarDataPtr}
 \subroutine{void *}{}{ptr}
-\argument{cGH *}{}{cctkGH}
+\argument{const cGH *}{}{cctkGH}
 \argument{int}{}{timelevel}
 \argument{char *}{}{name}
 \showcargs
@@ -3572,7 +3570,7 @@ The variable name should be in the form {\t <implementation>::<variable>}.
 \begin{CCTKFunc}{CCTK\_VarDataPtrB}{Returns the data pointer for a grid variable from the variable index or the variable name}
 \label{CCTK-VarDataPtrB}
 \subroutine{void *}{}{ptr}
-\argument{cGH *}{}{cctkGH}
+\argument{const cGH *}{}{cctkGH}
 \argument{int}{}{timelevel}
 \argument{int}{}{index}
 \argument{char *}{}{name} 
@@ -3601,7 +3599,7 @@ If the name if {\t NULL} the index will be used, if the index is negative the na
 \begin{CCTKFunc}{CCTK\_VarDataPtrI}{Returns the data pointer for a grid variable from the variable index}
 \label{CCTK-VarDataPtrI}
 \subroutine{void *}{}{ptr}
-\argument{cGH *}{}{cctkGH}
+\argument{const cGH *}{}{cctkGH}
 \argument{int}{}{timelevel}
 \argument{int}{}{index}
 \showcargs