Updates to style guide, plus addition of template header and source files.

Tom


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

3 files changed, 140 insertions, 4 deletions

diff --git a/doc/MaintGuide/Style.tex b/doc/MaintGuide/Style.tex
index 14d080d2..b266e763 100644
--- a/doc/MaintGuide/Style.tex
+++ b/doc/MaintGuide/Style.tex
@@ -73,12 +73,52 @@ The function grdoc should contain
 \item
 a description of the function, saying what it does.
 \item
+the functions called by this function.
+\item
 all function arguments with descriptions
 of what they are and what they are used for.
 \item
 the return codes should be described.
 \end{itemize}
 
+Note the that `calledby' field {\em should not} be filled in as
+this is unmaintainable.
+
+The standard grdoc function header is of the form
+
+\begin{verbatim}
+ /*@@
+   @routine    Template
+   @date       Fri Oct  6 10:51:49 2000
+   @author     Tom Goodale
+   @desc 
+   An example of grdoc
+   @enddesc 
+   @calls     templatefunc2
+   @calledby   
+   @history 
+ 
+   @endhistory 
+   @var     templatestring
+   @vdesc   string describing foobar
+   @vtype   const char *
+   @vio     in
+   @vcomment 
+ 
+   @endvar 
+
+   @returntype int *
+   @returndesc
+   0 - success
+   or the returncode of @seeroutine templatefunc2
+   @endreturndesc
+@@*/
+\end{verbatim}
+
+This is the form which will be created if you use the grdoc emacs mode.  
+The variable descriptions and the return code decription should be placed
+after the history so that they are close to the actual function.
+
 After the first actual release the history should be filled
 in with each change.
 
@@ -93,7 +133,7 @@ by lines of the form
 
 \begin{verbatim}
 #ifndef _NAMEOFHEADERFILEINCAPITALS_H_
-#define _NAMEOFHEADERFILEINCAPITALS_H_
+#define _NAMEOFHEADERFILEINCAPITALS_H_ 1
 
 ...body of header file...
 
@@ -120,14 +160,16 @@ extern "C"
 The Cactus header files ({\tt cctk\_<name>}) should only include
 information relevant for thorn programmers. 
 
+There is a template file in the doc/MaintGuide directory.
+
 \section{Source Files}
 
-Source files should have as their first line under the 
-grdoc header a line containing
+Source files should have as their first line after all the include
+files a line containing
 
 %\begin{verbatim}
 \vskip .3cm
-{\bf static char \*rcsid = "\$Header\$"; }
+{\bf static char $*$rcsid = "\$Header\$"; }
 %\end{verbatim}
 \vskip .3cm
 or the expanded rcs version of this.
@@ -139,6 +181,8 @@ functions.
 what I'm coming to like as a style, e.g.
 src/main/ScheduleInterface.c )
 
+There is a template file in the doc/MaintGuide directory.
+
 \section{Naming Conventions}
 
 All functions which may be used by thorns should have names beginning
@@ -162,8 +206,12 @@ names beginning with {\tt i}.
 All Cactus sourcefile names (except general utility files) should 
 use capitilised words without underscores.
 
+\section{Functions}
 
+All functions should have a grdoc header.
 
+They should have a single place of return at the end of the function to
+make it easy to tidy up and work out what is going on.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \end{cactuspart}
diff --git a/doc/MaintGuide/Template.c b/doc/MaintGuide/Template.c
new file mode 100644
index 00000000..bd109203
--- /dev/null
+++ b/doc/MaintGuide/Template.c
@@ -0,0 +1,67 @@
+ /*@@
+   @file      Template.c
+   @date      Wed Sep 13 20:10:24 2000
+   @author    Tom Goodale
+   @desc 
+   Template source file
+   @enddesc
+   @version  $Header$
+ @@*/
+
+#include "cctk.h"
+
+#ifdef HAVE_UNISTD_H
+#include <unistd.h>
+#endif /* HAVE_UNISTD_H */
+#ifdef HAVE_SYS_TIME_H
+#include <sys/time.h>
+#endif /* HAVE_SYS_TIME_H */
+#ifdef HAVE_SYS_TYPES_H
+#include <sys/types.h>
+#endif /* HAVE_SYS_TYPES_H */
+#ifdef HAVE_SYS_SOCKET_H
+#include <sys/socket.h>
+#endif /* HAVE_SYS_SOCKET_H */
+#ifdef HAVE_NETINET_IN_H
+#include <netinet/in.h>
+#endif /* HAVE_NETINET_IN_H */
+#ifdef HAVE_NETDB_H
+#include <netdb.h>
+#endif /* HAVE_NETDB_H */
+#ifdef HAVE_ARPA_INET_H
+#include <arpa/inet.h>
+#endif /* ARPA_INET_H */
+#ifdef HAVE_WINSOCK2_H
+#include <winsock2.h>
+#endif /* HAVE_WINSOCK2_H */
+
+#include "Template.h"
+
+static char *rcsid = "$Header$";
+
+CCTK_FILEVERSION(MaintGuide_Template_c)
+
+/********************************************************************
+ *********************     Local Data Types   ***********************
+ ********************************************************************/
+
+/********************************************************************
+ ********************* Local Routine Prototypes *********************
+ ********************************************************************/
+
+/********************************************************************
+ ********************* Other Routine Prototypes *********************
+ ********************************************************************/
+
+/********************************************************************
+ *********************     Local Data   *****************************
+ ********************************************************************/
+
+/********************************************************************
+ *********************     External Routines   **********************
+ ********************************************************************/
+
+/********************************************************************
+ *********************     Local Routines   *************************
+ ********************************************************************/
+
diff --git a/doc/MaintGuide/Template.h b/doc/MaintGuide/Template.h
new file mode 100644
index 00000000..adeb1955
--- /dev/null
+++ b/doc/MaintGuide/Template.h
@@ -0,0 +1,21 @@
+ /*@@
+   @header    Template.h
+   @date      Fri Oct  6 10:45:01 2000
+   @author    Tom Goodale
+   @desc 
+   This is a template header function
+   @enddesc
+   @version $Header$
+ @@*/
+
+#ifndef _TEMPLATE_H_
+#define _TEMPLATE_H_ 1
+
+#ifdef __cplusplus
+extern "C" 
+{
+
+}
+#endif
+
+#endif /* _TEMPLATE_H_ */