Changeset 505

Timestamp:

Apr 22, 2004, 12:33:38 PM (22 years ago)

Author:

Paul Price

Message:

Added discussion about Doxygen and the use of tags.

File:

• trunk/doc/misc/codeConventions.tex (modified) (9 diffs)

trunk/doc/misc/codeConventions.tex

@@ -1 @@
-%%% $Id: codeConventions.tex,v 1.13 2004-04-22 20:30:32 eugene Exp $
+%%% $Id: codeConventions.tex,v 1.14 2004-04-22 22:33:38 price Exp $
 \documentclass[panstarrs]{panstarrs}
 
@@ -137 +137 @@
 
 For an example of a properly formatted program, see
-Source File Example (sec. \ref{SourceExample}).
+Source File Example (\S\ref{SourceExample}).
 
 \subsection{Source Files}
@@ -233 +233 @@
 
 When preparing documents, you should ensure that lines of this length
-are not wrapped\footnote{If you are using the standard PSDC \LaTeX{}
-class file \file{panstarrs.cls}, \CODE|\begin{verbatim}
-... \end{verbatim}| will do this for you}.
+are not wrapped.  If you are using the standard PSDC \LaTeX{} class
+file \file{panstarrs.cls}, \CODE|\begin{verbatim} ... \end{verbatim}|
+will do this for you.
 
 \subsection{Wrapping Lines}
@@ -246 +246 @@
 
 \begin{verbatim}
-if(a < b ||
-   a > 2*b) {
-    x = (a + b + c) +
-    sin(z);
-}
+    if(a < b ||
+       a > 2*b) {
+        x = (a + b + c) +
+            sin(z);
+    }
 \end{verbatim}
 
@@ -393 +393 @@
 describe.
 
-See also Documentation Comments (sec. \ref{DocComments}).
+See also Documentation Comments (\S\ref{DocComments}).
 
 \subsubsection{Single-Line Comments}
@@ -400 +400 @@
 Short comments can appear on a single line indented to the level of
 the code that follows. If a comment can't be written in a single line,
-it should follow the \ref{ImplBlockComments}block comment format.
+it should follow the block comment format (\S\ref{ImplBlockComments}).
 
 \subsubsection{Trailing Comments}
@@ -440 +440 @@
 \label{DocComments} 
 
-\tbd{Need references to Doxygen here.}
+Doxygen\footnote{{\tt  www.doxygen.org}}  will   be  used  to  produce
+documentation of the types,  functions and variables without requiring
+much  extra  effort  for   the  programmer.   Comments  starting  with
+particular characters  (``tags'') are used by Doxygen  to identify the
+relevant code to be documented.
+
+Functions shall be tagged for Doxygenation by pre-pending them with a
+block comment (\S\ref{ImplBlockComments}) which starts with a
+\code{/**} instead of the usual \code{/*}.
+
+Variables shall be tagged for Doxygenation by appending their
+declaration with an end-of-line comment which starts with a
+\code{///<} instead of the usual \code{//}.
+
+An example of a function definition employing Doxygen-compatible
+comments follows:
+
+\begin{verbatim}
+/** This is a really cool function.
+ *  It does many really cool things.
+ */
+int reallyCoolFunction(int aNumber,     ///< This is a number 
+                       float aRealNumber ///< This is a real number
+                       )
+{
+    char *aString;                      ///< This is a string used to do stuff.
+
+    /* Do really cool stuff */
+    ...
+}
+\end{verbatim}
 
 If you need to give information about a type, interface, or variable
-that isn't appropriate for doxygenation, use an implementation block
-comment (sec. \ref{ImplBlockComments}) or single-line comment (sec. \ref{SingleLineComment})
-immediately \textit{before} the code. For example, details about the
-implementation of a type should go in in such an implementation block
-comment \textit{before} the start of the implementation, not in the
-doxygen comment.
+that isn't appropriate for doxygenation, use a normal implementation
+block comment (\S\ref{ImplBlockComments}) or single-line comment
+(\S\ref{SingleLineComment}) immediately \textit{before} the code (as
+exampled above). For example, details about the implementation of a
+type should go in in such an implementation block comment
+\textit{before} the start of the implementation, not in the doxygen
+comment.
 
 %------------------------------------------------------------------------------
@@ -747 +778 @@
 expected) when the fall-through is between multiple case statements.
 
-Every \code{switch} statement should include a default case,
-which should come last. The \code{break} in the default case
-is redundant, but it prevents a fall-through error if later another
-\code{case} is later (and illegally) added after the default clause.
-
-When switching on an enumerated type, if all the elements of the
-type are included in the switch a default clause should still be
-added (not all compilers diagnose missing elements).  In this case,
-the action in the default clause should be to generate an error
-\and abort.
+Every \code{switch} statement should include a default case, which
+should come last. The \code{break} in the default case is redundant,
+but it prevents a fall-through error if later another \code{case} is
+later (and illegally) added after the default clause.
+
+When switching on an enumerated type, if all the elements of the type
+are included in the switch a default clause should still be added (not
+all compilers diagnose missing elements).  In this case, the action in
+the default clause should be to generate an error and abort.
 
 \subsection{label Statements}
@@ -1493 +1523 @@
 \item \code{--indent=spaces=4} - This option tells \code{astyle} to
   use 4 spaces per indent level.
-
-bibliographystyle{plain}
+\end{itemize}
+
+\bibliographystyle{plain}
 \bibliography{panstarrs}