From 7dec069fa0ad530b77c3178e96852a277d857a3e Mon Sep 17 00:00:00 2001 From: goodale Date: Fri, 6 Oct 2000 09:07:41 +0000 Subject: 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 --- doc/MaintGuide/Style.tex | 56 ++++++++++++++++++++++++++++++++++++--- doc/MaintGuide/Template.c | 67 +++++++++++++++++++++++++++++++++++++++++++++++ doc/MaintGuide/Template.h | 21 +++++++++++++++ 3 files changed, 140 insertions(+), 4 deletions(-) create mode 100644 doc/MaintGuide/Template.c create mode 100644 doc/MaintGuide/Template.h 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\_}) 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 +#endif /* HAVE_UNISTD_H */ +#ifdef HAVE_SYS_TIME_H +#include +#endif /* HAVE_SYS_TIME_H */ +#ifdef HAVE_SYS_TYPES_H +#include +#endif /* HAVE_SYS_TYPES_H */ +#ifdef HAVE_SYS_SOCKET_H +#include +#endif /* HAVE_SYS_SOCKET_H */ +#ifdef HAVE_NETINET_IN_H +#include +#endif /* HAVE_NETINET_IN_H */ +#ifdef HAVE_NETDB_H +#include +#endif /* HAVE_NETDB_H */ +#ifdef HAVE_ARPA_INET_H +#include +#endif /* ARPA_INET_H */ +#ifdef HAVE_WINSOCK2_H +#include +#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_ */ -- cgit v1.2.3