Added some error return codes.

git-svn-id: http://svn.cactuscode.org/arrangements/CactusNumerical/SpaceMask/trunk@28 a491c6a4-70bf-4b89-8b36-d6c0cb1f094e

1 files changed, 15 insertions, 5 deletions

diff --git a/doc/documentation.tex b/doc/documentation.tex
index 28df841..349de9b 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -91,8 +91,13 @@ int SpaceMask\_RegisterType(const char* \emph{type\_name},
 \noindent An appropriate number of bits of the mask are allocated to
 hold a unique value for the $n$ states specified by the \emph{nstates}
 argument. The registration must take place before the type can be
-used, so for instance, this could be scheduled at CCTK\_STARTUP. New
-states can be added to an already allocated type using the function:
+used, so for instance, this could be scheduled at CCTK\_STARTUP. The
+function returns a $-1$ if the required states cannot be allocated
+(for example, if there are not enough free bits remaining in the
+mask), otherwise it returns $0$.
+
+New states can be added to an already allocated type using the
+function:
 
 \indent\parbox{\linewidth}{
 \vspace{\baselineskip}\noindent\texttt{
@@ -112,6 +117,9 @@ int SpaceMask\_AppendStatesToType(const char* \emph{type\_name},
 \noindent A number of new bits will be added to the specified type
 appropriate to hold the number of existing states plus the extra
 states. The allocated bits need not be contiguous within the mask.
+The function returns $0$ if successful, otherwise a $-1$ if the new
+states could not be allocated.
+
 
 \subsubsection{Setting and checking mask states}
 
@@ -189,9 +197,11 @@ CCTK\_INT SpaceMask\_GetStateBits(const char* \emph{type\_name},
 \noindent Each of these functions returns a CCTK\_INT8 which holds the
 bitmask corresponding to the given type or state. For example, if a
 given type uses three bits of the mask, the returned value could be
-the integer corresponding to the bitfield 001110000\ldots, where the
-location of 1s indicates the bits which have been allocated to the
-given type.
+the integer corresponding to the bitfield $001110000$\ldots, where the
+location of $1$s indicates the bits which have been allocated to the
+given type. A return value of $0$ indicates that the bitmask could
+not be determined for some reason (for example, the requested state
+was not previously registered).
 
 The following macros have been defined for fast setting and checking
 of the mask by direct bitwise operations: