redo description of CCTK_SyncGroup()

* use modern FunctionDescription environment
* document that GH argument is pointer-to-const
  (i.e. document that  CCTK_SyncGroup  doesn't modify the GH)
* document that this is a collective operation
* add an example


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

1 files changed, 74 insertions, 17 deletions

diff --git a/doc/ReferenceManual/CCTKReference.tex b/doc/ReferenceManual/CCTKReference.tex
index 83535bd9..c54c774b 100644
--- a/doc/ReferenceManual/CCTKReference.tex
+++ b/doc/ReferenceManual/CCTKReference.tex
@@ -9822,16 +9822,45 @@ Reduces a list of local arrays globally
 
 
 % CommOverloadables.c
-\begin{CCTKFunc}{CCTK\_SyncGroup}{Synchronise the ghostzones for a group of grid variables}
+\begin{FunctionDescription}{CCTK\_SyncGroup}
 \label{CCTK-SyncGroup}
-\subroutine{int}{integer}{istat}
-\argument{cGH *}{CCTK\_POINTER}{cctkGH}
-\argument{const char *}{character*(*)}{group}
-\showargs
-\begin{params}
-\parameter{cctkGH}{pointer to CCTK grid hierarchy}
-\end{params}
-\begin{discussion}
+Synchronise the ghostzones for a group of grid variables
+
+\begin{SynopsisSection}
+\begin{Synopsis}{C}
+\begin{verbatim}
+#include "cctk.h"
+int status = CCTK_SyncGroup(const cGH* GH, const char* group_name)
+\end{verbatim}
+\end{Synopsis}
+\begin{Synopsis}{Fortran}
+\begin{verbatim}
+#include "cctk.h"
+integer status
+CCTK_POINTER GH
+character*(*) group_name
+call CCTK_SyncGroup(status, GH, group_name)
+\end{verbatim}
+\end{Synopsis}
+\end{SynopsisSection}
+
+\begin{ResultSection}
+\begin{Result}{0}
+Success.
+\end{Result}
+\end{ResultSection}
+
+\begin{ParameterSection}
+\begin{Parameter}{GH}
+A pointer to a Cactus grid hierarchy.
+\end{Parameter}
+\begin{Parameter}{group\_name}
+The full name (Implementation::group or Thorn::group) of the group
+to be synchronized.
+\end{Parameter}
+\end{ParameterSection}
+
+\begin{Discussion}
 Only those grid variables which have communication enabled
 will be synchronised. This is usually equivalent to the variables
 which have storage assigned, unless communication has been explicitly
@@ -9842,16 +9871,44 @@ from within a thorn, is to use the \code{SYNC} keyword in a thorns
 \code{schedule.ccl} file to indicate which groups of variables need
 to be synchronised on exit from the routine. This latter method is
 the preferred method from synchronising variables.
-\end{discussion}
-\begin{examples}
-\begin{tabular}{@{}p{3cm}cp{11cm}}
-\end{tabular}
-\end{examples}
-\begin{errorcodes}
-\end{errorcodes}
-\end{CCTKFunc}
 
+Note that \code{CCTK\_SyncGroup} is a collective operation, so in the
+multiprocessor case you {\em must\/} call this function in parallel on
+{\em each\/} processor, passing the same \code{group\_name} argument.
+\end{Discussion}
 
+\begin{ErrorSection}
+\begin{Error}{-1}
+\code{group\_name} was invalid.
+\end{Error}
+\begin{Error}{-2}
+The driver returned an error on syncing the group.
+\end{Error}
+\end{ErrorSection}
+
+\begin{ExampleSection}
+\begin{Example}{C}
+\begin{verbatim}
+#include "cctk.h"
+#include "cctk_Arguments.h"
+
+/* this function synchronizes the ADM metric */
+void synchronize_ADM_metric(CCTK_ARGUMENTS)
+{
+DECLARE_CCTK_ARGUMENTS      /* defines "magic variable" cctkGH */
+
+const int status = CCTK_SyncGroup(cctkGH, "ADMBase::metric");
+if (status < 0)
+        CCTK_VWarn(CCTK_WARN_ABORT, __LINE__, __FILE__, CCTK_THORNSTRING,
+"***** synchronize_ADM_metric():\n"
+"        failed to synchronize ADM metric!\n"
+"        (CCTK_SyncGroup() returned error code %d)\n"
+                  ,
+                  status);                                 /*NOTREACHED*/
+\end{verbatim}
+\end{Example}
+\end{ExampleSection}
+\end{FunctionDescription}
 
 %%%%%
 % TTT