Index: trunk/doc/misc/codeConventions.tex
===================================================================
--- trunk/doc/misc/codeConventions.tex	(revision 505)
+++ trunk/doc/misc/codeConventions.tex	(revision 514)
@@ -1,3 +1,3 @@
-%%% $Id: codeConventions.tex,v 1.14 2004-04-22 22:33:38 price Exp $
+%%% $Id: codeConventions.tex,v 1.15 2004-04-23 21:57:43 eugene Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -171,5 +171,5 @@
 e.g. for file \file{psThing.h}:
 \begin{verbatim}
-/*
+/** \file psThing.h
  * Support for psThings
  */
@@ -186,5 +186,8 @@
 } psThing;
 
+/// make a new psThing
 psThing *psThingAlloc(int nthing);
+
+/// free an existing psThing
 void psThingFree(psThing *thing);
 
@@ -486,7 +489,6 @@
 
 All globally-visible symbols must be declared in a suitable header
-(.h) file.  Global private symbols (i.e.  those named \code{p_ps})
-should not appear in public header files, but rather in files whose
-names begin \code{p_ps}.
+(.h) file.  Global private symbols should not appear in public header
+files, but rather in separate, private header files.
 
 \subsection{Number Per Line}
@@ -576,7 +578,7 @@
 \item 
 Function declarations should be preceeded by a short comment
-describing what the function does.
-
-\tbd{Discuss Doxygen}
+describing what the function does.  These comment blocks should
+include doxygen-style comments to provide a brief desription as well
+as other warnings, bugs, etc as needed.
 
 \item The function's type should appear on the same line as the
@@ -871,4 +873,5 @@
 rigid adherence to the guideline.
  
+{ \small 
 \begin{tabular}{lp{3in}p{3in}}
 \textbf{Identifier Type} &
@@ -898,14 +901,10 @@
 
 The names of all externally visible functions (i.e. all those that are
-not declared \code{static}) should be verbal phrases, in mixed
-case. The first two characters should be \code{ps}, with the first
-letter of each internal word capitalized.
-
-Functions that are visible at global scope but are not considered part
-of the public interface should be prefixed \code{p_ps}.
-
-Functions that are local to a file should \textit{not} start
-\code{ps} (or \code{p_ps}).
- 
+not declared \code{static}) should be verbal phrases, in mixed case.
+
+Namespaces should be protected by using special naming prefixes to
+restrict the name space in particular libraries.  For example, the
+PSLib functions are all prefixed with \code{ps}.
+
 &
 
@@ -927,10 +926,4 @@
 standard. Non-globally visible words should start with a lowercase
 first letter; Internal words start with capital letters.
-
-Variables visible at global scope should begin with \code{ps},
-or \code{p_ps} if not considered part of the public interface.
-Variables that are local to a file should \textit{not} start
-with \code{ps} (or \code{p_ps}). These variables should be Capitalised
-at the beginning of each word.
 
 Variable names should be short yet meaningful. The choice of a
@@ -943,5 +936,7 @@
 
 &
-\code{int i; char c; float myWidth;}\hfil\break
+\code{int i;}\hfil\break
+\code{char c;}\hfil\break
+\code{float myWidth;}\hfil\break
 \hfil\break
 \code{int psNumOTA;}\hfil\break
@@ -959,11 +954,4 @@
 enumerated types.
 
-The names of all enumerated types and C-preprocessor symbols (but not
-variables declared \code{const}) declared should start with
-\code{PS_} or \code{P_PS_} and the rest of the name should
-be uppercase with words separated by underscores (\code{_}). In the case of
-system utilities implemented as macros, the names may conform to the
-usual \PS{} conventions (e.g. \code{psAlloc}).
-
 &
 \code{#define PS_MAXLEN 40}\hfil\break
@@ -971,4 +959,5 @@
 
 \end{tabular}
+}
 
 %------------------------------------------------------------------------------
@@ -978,7 +967,8 @@
 \subsection{When to Make Symbols Global}
 
-Declare all functions and variables \code{static} within a
-file if at all possible (n.b. do not confuse this use of \code{static}
-with its usage to make auto-variables within a function persistent).
+Declare all functions and top-level variables \code{static} within a
+file if they are not needed outside of the file.  {\bf Note:} do not
+confuse this use of \code{static} with its usage to make
+auto-variables within a function persistent.
 
 \subsection{Constants}
@@ -987,4 +977,37 @@
 small integers such as -1, 0, and 1 which are permitted to e.g. appear
 in a \code{for} loop as counter values.  
+
+\subsection{Type Qualifiers (const and restrict)}
+
+All interfaces and type definitions should use \code{const} and
+\code{restrict} wherever appropriate. For example,
+\begin{verbatim}
+typedef struct {
+    int n;
+    float *restrict vec;
+} psVec;
+
+psVec *psVecAdd(const restrict* psVec s1, const restrict* psVec s2); 
+\end{verbatim}
+
+\textit{{\bf Note:} compilers are free to ignore the \code{restrict}
+keyword, so all code should be written to explicitly handle aliasing}.
+
+\subsection{structs and typedefs}
+
+All structs should be defined as \code{typedef}s.
+
+A struct should not include a struct
+tag unless it's self-referential; E.g.
+\begin{verbatim}
+typedef struct myStruct { 		// Omit "myStruct"
+    int x;
+} myStruct;
+
+typedef struct yourStruct { 		// OK
+    struct yourStruct *next;
+    int x;
+} yourStruct;
+\end{verbatim}
 
 \subsection{Variable Assignments}
@@ -1101,15 +1124,29 @@
 
 \subsubsection{Special Comments}
+
+Doxygen has special comments which are used to provide specific notes
+in the code.  These are added in as special entries and sections in
+the Doxygen-generated documentation.  These special comments should be
+used in addition to the Doxygen usage to make these types of
+conditions easily searchable.
+
 \begin{itemize}
 \item 
-Use \code{XXX} in a comment to flag something that is bogus but works.
+Use \code{\warning} in a comment to flag something that is bogus but works.
 
 \item 
-Use \code{FIXME} to flag something that is bogus and broken.
-
-\tbd{Check Doxygen versions of these special comments. I could not
-find any occurrence of \code{@notused@} in the Doxygen documentation}
-\item
-Use \code{NOTREACHED} to indicate a line of code that cannot be reached,
+Use \code{\bug} to flag something that is bogus and broken.
+
+\item 
+Use \code{\todo} to note additional work to be done 
+
+\item 
+Use \code{\note} to make other general notes 
+
+\item 
+Use \code{\test} to list test cases 
+
+\item
+Use \code{\notreached} to indicate a line of code that cannot be reached,
 e.g.
 \begin{verbatim}
@@ -1121,5 +1158,5 @@
 
 \item 
-Use \code{NOTUSED} to indicate unused arguments to a function:
+Use \code{\notused} to indicate unused arguments to a function:
 e.g.
 \begin{verbatim}
@@ -1133,85 +1170,4 @@
 \end{verbatim}
 \end{itemize}
-
-\subsubsection{\label{LAllocFree}10.4.6     Constructors/Destructors}
-
-Type definitions should always be accompanied by prototypes for
-their constructors and destructors:
-
-\begin{itemize}
-\item  The constructor should consist of the type name followed by
-\code{Alloc}; e.g. a type \code{psImage} would
-be created by a function
-\begin{verbatim}
-psImage *psImageAlloc(int nrow, int ncol);
-\end{verbatim}
-
-\item  Similarly, the type should be freed with a destructor named
-\code{typeFree}, e.g.
-\begin{verbatim}
-void psImageFree(psImage *img);
-\end{verbatim}
-
-\item  The constructor should never return \code{NULL}, and
-no code calling the constructor should ever check the return value.
-
-\item  The destructor must not return a value.
-
-\item  The destructor should handle being passed \code{NULL}
-by simply returning immediately. This should not be treated as
-an error condition.
-
-\item  The destructor should call \code{psMemGetRefCounter}; if the value is greater
-  than one, the destructor should simply call \code{psMemDecrRefCounter} and return.
-
-\end{itemize}
-
-\subsection{\label{LConvOps}Naming Conversion Operators}
-
-When defining a function to convert from one type to another, the
-name should be of the form \code{psOldToAlloc}, e.g.\hfil\break
-\code{psEquatorialToEcliptic} (\emph{not} \code{psEquatorial2Ecliptic}).
-
-\subsection{Order of I/O Arguments}
-
-Functions that assign to a variable should list that argument
-\textit{first} (i.e. following the pattern of \code{strcpy}); e.g.
-\begin{verbatim}
-void psAddToVector(restrict psVec *outVec, const restrict psVec *inVec,
-		   int val);
-\end{verbatim}
-
-\subsection{Type Qualifiers (const and restrict)}
-
-All interfaces and type definitions should use \code{const} and
-\code{restrict} wherever appropriate. For example,
-\begin{verbatim}
-typedef struct {
-    int n;
-    float *restrict vec;
-} psVec;
-
-psVec *psVecAdd(const restrict* psVec s1, const restrict* psVec s2); 
-\end{verbatim}
-
-\textit{{\bf Note:} compilers are free to ignore the \code{restrict}
-keyword, so all code should be written to explicitly handle aliasing}.
-
-\subsection{structs and typedefs}
-
-All structs should be defined as \code{typedef}s.
-
-A struct should not include a struct
-tag unless it's self-referential; E.g.
-\begin{verbatim}
-typedef struct myStruct { 		// Omit "myStruct"
-    int x;
-} myStruct;
-
-typedef struct yourStruct { 		// OK
-    struct yourStruct *next;
-    int x;
-} yourStruct;
-\end{verbatim}
 
 %------------------------------------------------------------------------------