cgal/Packages/Developers_manual/code_format_internal.tex

\subsection*{Internal releases}
\ccIndexSubsubitemBegin{source files}{headings for}{internal releases}

The heading of a \cgal\ source file that is submitted (for an internal release)
should have the following format:

\begin{verbatim}
// ============================================================================
//
// Copyright (c) 1997-2001 The CGAL Consortium
//
// This software and related documentation is part of an INTERNAL release
// of the Computational Geometry Algorithms Library (CGAL). It is not
// intended for general use.
//
// ----------------------------------------------------------------------------
//
// release       : $CGAL_Revision$
// release_date  : $CGAL_Date$
//
// file          : include/CGAL/Min_ellipse_2.h
// package       : Min_ellipse_2 (3.5.4)
// chapter       : Geometric Optimisation
//
// source        : web/Optimisation/Min_ellipse_2.aw
// revision      : $Revision$
// revision_date : $Date$
//
// author(s)     : Bernd Gaertner, Sven Schoenherr
// maintainer    : Sven Schoenherr <sven@inf.fu-berlin.de>
// coordinator   : ETH Zuerich (Bernd Gaertner <gaertner@inf.ethz.ch>)
//
// implementation: 2D Smallest Enclosing Ellipse
// ============================================================================
\end{verbatim}

The following rules apply to the fields:

\begin{itemize}
\item {\tt <release>}, {\tt <release\_date>}, and {\tt <maintainer>} must be 
      present but need not be filled in (since they will be overwritten when 
      the internal release is created). 
\item {\tt <file>}, {\tt <package>}, {\tt <author(s)>}, and
      {\tt <coordinator>} are obligatory and must be filled in.
\item {\tt <chapter>}, {\tt <source>}, {\tt <revision>}, {\tt <revision\_date>},
      and {\tt <implementation>} are optional.
\item For the {\tt <coordinator>} field, the coordinating site as well as
      the person in charge is named, together with the person's e-mail address.
\item Optionally, the next-to-last line may contain a comment on the
      functionality of the source file's content.
\end{itemize}

When a new internal release is generated\ccIndexMainItem{internal release}, 
the fields {\tt <release>} and {\tt <release\_date>} are overwritten. 
The release label for the internal release is composed of the number of the 
next public release, an~{\tt I} (for ``internal''), and a positive integer that 
represents the internal release number (\eg, e.g.~{\tt CGAL-2.2-I-1} was the 
number of the first internal release after public release 2.1).%
\ccIndexSubitem{internal release}{number} 
If the field {\tt <maintainer>} is blank, it is filled in with the name and
email address of the last person who submitted the package.%
\ccIndexSubitem{\tt maintainer}{field in file header} 
All other fields between the two delimiting 
lines of equal signs remain untouched.
\ccIndexSubsubitemEnd{source files}{headings for}{internal releases}

\subsection*{Public releases}
\ccIndexSubsubitemBegin{source files}{headings for}{public releases}

When a new public release is generated, only the fields {\tt <file>},
{\tt <package>}, \mbox{{\tt <chapter>}} (if present), and {\tt <author(s)>}
are kept.  The heading of the source file (generated by the 
\texttt{make\_public\_header} script 
(see Chapter~\ref{chap:releases})
will become something like this:


\begin{verbatim}
// ============================================================================
//
// Copyright (c) 1997-2000 The CGAL Consortium
//
// This software and related documentation is part of the
// Computational Geometry Algorithms Library (CGAL).
//
// This software and documentation is provided "as-is" and without warranty
// of any kind. In no event shall the CGAL Consortium be liable for any
// damage of any kind.
//
// Every use of CGAL requires a license. 
//
// Academic research and teaching license
// - For academic research and teaching purposes, permission to use and copy
//   the software and its documentation is hereby granted free of charge,
//   provided that it is not a component of a commercial product, and this
//   notice appears in all copies of the software and related documentation. 
//
// Commercial licenses
// - A commercial license is available through Algorithmic Solutions,
//   (http://www.algorithmic-solutions.com). 
// - Commercial users may apply for an evaluation license by writing to
//   Algorithmic Solutions (contact@algorithmic-solutions.com).
//
// The CGAL Consortium consists of Utrecht University (The Netherlands),
// ETH Zurich (Switzerland), Freie Universitaet Berlin (Germany),
// INRIA Sophia-Antipolis (France), Martin-Luther-University Halle-Wittenberg
// (Germany), Max-Planck-Institute Saarbrucken (Germany), RISC Linz (Austria),
// and Tel-Aviv University (Israel).
//
// ----------------------------------------------------------------------------
//
// release       : CGAL-2.1
// release_date  : 2000, January 11
//
// file          : include/CGAL/Min_ellipse_2.h
// package       : Min_ellipse_2 (3.5.4)
// chapter       : Geometric Optimisation
// author(s)     : Bernd Gaertner, Sven Schoenherr
//
// email         : cgal@cs.uu.nl
//
// ============================================================================
\end{verbatim}
\ccIndexSubsubitemEnd{source files}{headings for}{public releases}
\ccIndexSubitemEnd{source files}{headings for}


\section{Requirements and recommendations}
\label{sec:code_format_doc_req_and_rec}

\noindent
Requirements:
\begin{itemize}
   \item Follow the naming schemes outlined above.
   \item Provide typedefs of template arguments as necessary to make the
         template parameters accessible elsewhere.
   \item Label member function and parameters with \ccc{const} where 
         appropriate
   \item Use \CC-style type casts.
   \item Protect header files from multiple inclusions.
   \item Obey the code format rules outlined above.
   \item Provide a header for each submitted file in the proper format.
\end{itemize}