/** @page libsbml-coding Coding conventions for libSBML

The following is a collection of guidelines for libSBML authors and other
interested persons to follow when writing libSBML code and documenting it.

<center>
<table border="0">
<tr><td style="font-size: small;">
@ref coding-general @n
@ref coding-doxygen-summary @n
@ref coding-doc-h @n
@ref coding-doc-cpp @n
</td></tr>
</table>
</center>


LibSBML's application programming interface (API) is documented using a
combination of tools: for C++, C and Python, we use the open-source
software tool <a href="http://www.doxygen.org">Doxygen</a>, written by
Dimitri van Heesch, and for the Java API, we use Javadoc.  In addition to
these main tools, we use several scripts to massage the output of SWIG to
produce better documentation.  The guidelines presented in this section are
oriented towards explaining how to organize code comments such that Doxygen
can produce good output, yet simultaneously make the comments in the code
be readable on their own.


@section coding-general General guidelines

@li Doxygen (and some humans) look in the .h file for a C++ class
definition.  Doxygen is a bit annoying in this regard because the content
of the .h file overrides the content of the .cpp file for the class members
(the methods and the data members).  That is, if you only modify the
comments in the class definition in the .cpp file, the changes will not be
reflected in the documentation produced by Doxygen.  Thus, when documenting
a class, concentrate on the .h files.  However, and confusingly, <em> C
functions must be documented in the .cpp files</em>.  Thus, the rule is:
document classes in .h files, but document C functions in the .cpp files.

@li Doxygen tags can be prefixed with either @c \@ or @c \\.  Since it
doesn't matter which, we may as well use the @c \@ form because it's also
used by Javadoc (and thus is easier to remember for Java programmers).

@li Doxygen comments consist of a C-style comment block beginning with two
asterisks (@c *) characters, as in the following example:
@verbatim
/**
 * Comments within which commands for Doxygen begin with the character @.
 */ 
@endverbatim
If your comment does @em not begin with <code>/**</code>, then it will be
ignored by Doxygen.  This can be either bad or good, depending on the
intention behind the comment.

@li Please write in complete sentences, with correct English grammar and
punctuation.  @em Do @em not treat new lines as new sentences or beginnings
of different comments.  Here is an example of what should be @em avoided:
@verbatim
/**
 * creates a foo object
 * given arg is the template
 */
@endverbatim
The text above doesn't end sentences with periods, doesn't begin sentences
with capitals, doesn't form complete sentences, etc.  When Doxygen is used
to generate HTML documentation from this, it turns into one long run-on
paragraph, and it's unreadable.

@li Please write sentences with @em two (2) spaces after the terminating
period, not one.  First, this makes the resulting text easier to read
compared to when sentence-ending periods are followed by only one space.
Second, text editing programs such as Emacs have special features to
recognize sentences based on this pattern, and they make proficient users
of those editors much happier because they can use sentence-oriented
editing commands.

@li Watch out that Doxygen automatically turns entity names it recognizes
in text into links to the definition of that entity.  This is usually what
you want to have happen; for example, when describing the Model class, you
may mention classes such as Species and Compartment, and those should be
turned into convenient links to their definitions in the API documentation.
However, sometimes you don't want that to happen.  To prevent Doxygen from
linking a word, put a percentage sign (\%) in front of it, as in @c
\%%Model.  Doxygen will remove the percentage sign and leave the rest of
the word unlinked, resulting in the plain word %Model appearing in the
finished document.

@li We are using a feature of Doxygen that makes it use the first sentence
of a documentation comment as the "brief" description of the entity being
described (which may be a class, a method, a class data member, a function,
a typedef, etc.).  This means that the first sentence up to a period or a
blank line will be pulled out separately and used as a one-line summary in
certain contexts by Doxygen.  The following is an example:
@verbatim
/**
 * This is the brief description.  After the first sentence, everything
 * else is part of the detailed description and not the brief one.  This
 * third sentence is also part of the detailed description.
 */
@endverbatim
Consequently, to emphasize this and remind people that this is going to
happen when the API documentation is generated, it is better to format the
text in the as in the following example:
@verbatim
/**
 * This is the brief description.
 *
 * This is the beginning of the detailed description....
 */
@endverbatim
The visual split makes it really obvious what's going to happen.

@li Please try to limit lengths of lines to 79 characters long or less.
This makes code and documentation generally easier to read and edit in
different software tools.  Sometimes it's too difficult to avoid a long
line, and then it's okay, but generally it's possible to reformat code in
such away as to keep things to 79 characters.

@li Sometimes code is meant to be part of the internal implementation and
not advertised to users of the library.  To make Doxygen ignore blocks of
code, wrap the code with the comment
@verbatim
/** @cond doxygen-libsbml-internal */
@endverbatim
at the beginning and 
@verbatim
/** @endcond doxygen-libsbml-internal */
@endverbatim
at the end of the block.  (Explanation: this sets up a conditional that
will only be "seen" by Doxygen if the symbol "doxygen-libsbml-internal" is
defined.  Since it's never defined in the Doxygen configuration, it will
the block will be ignored.)


@section coding-doxygen-summary Summary of commonly-used Doxygen commands in libSBML

The following is a summary of the doxygen commands we have found useful so
far in documenting libSBML.  This is only intended as a quick orientation;
they are illustrated in the other sections below, and the complete details
of their definitions and use can be found online at the <a
href="http://www.doxygen.org">Doxygen</a> website.

<table border="0">
<tr><td class="simpletableleft" style="background-color: #cccccc;">Command</td>
    <td class="simpletableleft" style="background-color: #cccccc;">Meaning</td><td></td></tr>

<tr><td class="simpletableleft">\@file</td>
<td class="simpletableright">
Defines the name of the current file.</td><td></td></tr>

<tr><td class="simpletableleft">\@brief</td>
<td class="simpletableright">
Provides a one-sentence description of the entity being described (a file,
a class, etc.).</td><td></td></tr>

<tr><td class="simpletableleft">\@author</td>
<td class="simpletableright">
Names the author of the entity being described (a file, a class, etc.).
</td><td></td></tr>

<tr><td class="simpletableleft">\@c</td>
<td class="simpletableright">
Puts the following word in typewriter ("code") font.  To style more than one
word, use <code>&lt;code&gt;the words&lt;/code&gt;</code>.  If you need to
put something that contains HTML tags in typewriter font, use the
<code>&lt;code&gt;the words&lt;/code&gt;</code> form, and use the HTML
character codes <code>\&lt;</code> and<code>\&gt;</code> to embed the
openening '@c &lt;' and '@c &gt;' characters inside <code>the words</code>.
</td><td></td></tr>

<tr><td class="simpletableleft">\@em</td>
<td class="simpletableright">
Puts the following word in italic font, for emphasis.  To put multiple words
in italics, use <code>&lt;em&gt;the words&lt;/em&gt;</code>.
</td><td></td></tr>

<tr><td class="simpletableleft">\@n</td>
<td class="simpletableright">
Forces a newline, like HTML's <code>&lt;br&gt;</code>.
</td><td></td></tr>

<tr><td class="simpletableleft">\@p</td>
<td class="simpletableright">
Puts the following word in typewriter ("code") font.  This form is preferred
when the word is a parameter to a method or function.
</td><td></td></tr>

<tr><td class="simpletableleft">\@li</td>
<td class="simpletableright">
Starts (or continues) a bullet list.  You can insert the first @c \@li in
a comment, and the item will continue until a paragraph break or the
next @c \@li command.  (Note: even though Doxygen will also recognize
hyphens at the beginning of a line as starting a  list item, avoid using 
that approach in favor of the @c \@li command.
</td><td></td></tr>

<tr><td class="simpletableleft">\@class</td>
<td class="simpletableright">
Declares that the following documentation block refers to the named class.
Useful only when the block does not immediately precede the class
definition (e.g., when it's at the beginning of the file). 
</td><td></td></tr>

<tr><td class="simpletableleft">\@param</td>
<td class="simpletableright">
Declares a parameter to a method or function.  The first word following
@c \@param will be the name of the parameter, and the rest of the text (up to
a period or blank) will be used as the description.
</td><td></td></tr>

<tr><td class="simpletableleft">\@return</td>
<td class="simpletableright">
Declares the return value from a method or function.
</td><td></td></tr>

<tr><td class="simpletableleft">\@see</td>
<td class="simpletableright">
Formats a reference to another entity in the documentation.  Commonly used
to refer to related classes or methods.
</td><td></td></tr>

<tr><td class="simpletableleft">\@note</td>
<td class="simpletableright">
Formats the following paragraph with the heading "Note:".  Useful to call
out something special about a class, function, file or other entity, such
as a behavior that should be brought to the attention of users or a note
about API changes compared to previous versions of the software or SBML.
As a convention, please put @c \@note blocks at the end of a documentation
block, for uniformity in the API documentation.
</td><td></td></tr>

<tr><td class="simpletableleft">\@warning</td>
<td class="simpletableright">
Formats the following paragraph with the heading "Warning:".  This is a
stronger statement than \@note, and is useful to call attention to
backward-incompatible changes or potentially error-provoking situations.
As a convention, please put @c \@warning blocks at the end of a documentation
block, for uniformity in the API documentation.
</td><td></td></tr>

<tr><td class="simpletableleft">\@bug</td>
<td class="simpletableright">
Formats the following paragraph with the heading "Bugs:".  Useful to
indicate that something is known to be a problem in some part of the code. 
As a convention, please put @c \@bug blocks at the end of a documentation
block, for uniformity in the API documentation.
</td><td></td></tr>

</table>

Many HTML commands will work in comments for Doxygen.  For example, a
common one is the @c a tag for linking text to a URL, as in <code>&lt;a
href="http://sbml.org"&gt;home page&lt;/a&gt;</code>.



@section coding-doc-h Guidelines for documenting .h files

It is important to note that the documentation of global functions,
variables, typedefs, and enums will only be included in the output of
Doxygen if the file they are in is documented as well.

@li Here is a template header file suitable for use when creating a new .h
file for libSBML (and in fact, it's the same for .cpp files, too):
@verbatim
/**
 * @file    [filename]
 * @brief   [succinct description of what's in this file]
 * @author  [author's name]
 *
 * $Id$
 * $HeadURL$
 *
 *<!---------------------------------------------------------------------------
 * This file is part of libSBML.  Please visit http://sbml.org for more
 * information about SBML, and the latest version of libSBML.
 *
 * Copyright 2005-2009 California Institute of Technology.
 * Copyright 2002-2005 California Institute of Technology and
 *                     Japan Science and Technology Corporation.
 * 
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation.  A copy of the license agreement is provided
 * in the file named "LICENSE.txt" included with this software distribution
 * and also available online as http://sbml.org/software/libsbml/license.html
 *----------------------------------------------------------------------- -->*/
@endverbatim
Of course, you should substitute appropriate content where the text is
bracked by @c [ and @c ].  The @c $Id$ and @c $HeadURL$ keywords will
automatically be substituted by CVS or SVN upon the first check-in.  The
following is an complete example taken from an actual libSBML file at the
time of this writing:
@verbatim
/**
 * @file    Compartment.h
 * @brief   The libSBML class of object implementing SBML's Compartment.
 * @author  Ben Bornstein
 *
 * $Id: libsbml-coding.txt 7249 2008-06-26 22:48:40Z bbornstei $
 * $HeadURL: https://sbml.svn.sourceforge.net/svnroot/sbml/trunk/libsbml/src/sbml/Compartment.h $
 *
 *<!---------------------------------------------------------------------------
 * This file is part of libSBML.  Please visit http://sbml.org for more
 * information about SBML, and the latest version of libSBML.
 *
 * Copyright 2005-2009 California Institute of Technology.
 * Copyright 2002-2005 California Institute of Technology and
 *                     Japan Science and Technology Corporation.
 * 
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation.  A copy of the license agreement is provided
 * in the file named "LICENSE.txt" included with this software distribution
 * and also available online as http://sbml.org/software/libsbml/license.html
 *----------------------------------------------------------------------- -->*/

#ifndef Compartment_h
#define Compartment_h
...
@endverbatim

@li A .h file will typically have a class declaration in it.  The @em
normal way that one would document the class is to put a comment block in
front of the class declaration, as in the following fragment:
@verbatim
/**
 * The libSBML class implementing SBML's CompartmentType construct.
 *
 * CompartmentTypes in SBML are ...
 */
class LIBSBML_EXTERN CompartmentType : public SBase
{
public:
...
@endverbatim
Unfortunately, we are hit here by a small problem of how to generate
descriptions for different programming languages from the same source
files.  In particular, those class declarations in the .h files are usually
surrounded by <code>\#ifdef __cplusplus</code>, which means they become
invisible when we use Doxygen to generate the descriptions for anything
other than C++.  Thus, for the special case of documentation of classes,
<em>please put the documentation in the file header</em> rather that ahead
of the class itself in the file.  The following example illustrates this
procedure (and note how more than one class can be described in the
header):
@verbatim
/**
 * @file    CompartmentType.h
 * @brief   Definitions of CompartmentType and ListOfCompartmentTypes.
 * @author  Ben Bornstein
 *
 * $Id: CompartmentType.h 7249 2008-06-26 22:48:40Z mhucka $
 * $Source: /cvsroot/sbml/libsbml/src/sbml/CompartmentType.h,v $
 *
 *<!---------------------------------------------------------------------------
 * This file is part of libSBML.  Please visit http://sbml.org for more
 * information about SBML, and the latest version of libSBML.
 *
 * Copyright 2005-2009 California Institute of Technology.
 * Copyright 2002-2005 California Institute of Technology and
 *                     Japan Science and Technology Corporation.
 * 
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation.  A copy of the license agreement is provided
 * in the file named "LICENSE.txt" included with this software distribution
 * and also available online as http://sbml.org/software/libsbml/license.html
 *------------------------------------------------------------------------- -->
 * 
 * @class CompartmentType.
 * @brief LibSBML implementation of SBML's %CompartmentType construct.
 *
 * A <em>compartment type</em> in SBML is a grouping construct used to
 * establish a relationship between multiple Compartment objects.
 * ....
 *
 *
 * @class ListOfCompartmentTypes.
 * @brief LibSBML implementation of SBML's ListOfCompartmentTypes construct.
 * 
 * The various ListOf___ classes in SBML are merely containers used for
 * organizing the main components of an SBML model.  All are derived from
 *....
 */

#ifndef CompartmentType_h
#define CompartmentType_h
...
@endverbatim

@li For each method or data member in the class definition, include a
comment block ahead of it, making sure to provide at least a brief
description.  If it's a method and the method returns a value, use @c
\@return to describe the returned value; if it takes parameters, use @c
\@param to describe the parameters.  If you also need to refer to the
parameters in the textual description of the method, use the @c \@p
command.  The following example illustrates this:
@verbatim
/**
 * Creates a new CompartmentType, optionally with the given @p id and
 * @p name attribute values.
 *
 * In SBML, identifiers are required for CompartmentType objects;
 * however, the identifier does not have to be set at the time of
 * creation of the object, and instead can be set using the setId()
 * method on the SBase parent class.
 *
 * @param id a string, the identifier of this CompartmentType instance
 * @param name a string, the optional name of this
 */
CompartmentType (const std::string& id = "", const std::string& name = "");
@endverbatim

@li Please try to leave 2 blank lines between method declarations and other
items in the definitions of classes.  This makes it easier for the eye to
spot transitions between method definitions, despite the blank lines that
exist within comment blocks.  Here is an example taken from a class
definition in a .h file:
@verbatim
class LIBSBML_EXTERN CompartmentType : public SBase
{
public:

  /**
   * Creates a new CompartmentType, optionally with the given @p id and @p
   * name attribute values.
   *
   * In SBML, identifiers are required for CompartmentType objects;
   * however, the identifier does not have to be set at the time of
   * creation of the object, and instead can be set using the setId()
   * method on the SBase parent class.
   *
   * @param id a string, the identifier of this CompartmentType instance
   * @param name a string, the optional name of this
   */
  CompartmentType (const std::string& id = "", const std::string& name = "");


  /**
   * Destroys this CompartmentType.
   */
  virtual ~CompartmentType ();


  /**
   * Copy constructor; creates a copy of this CompartmentType.
   */
  CompartmentType(const CompartmentType& orig);


  /**
   * Assignment operator for CompartmentType.
   */
  CompartmentType& operator=(const CompartmentType& orig);
@endverbatim





@section coding-doc-cpp Guidelines for documenting .cpp files

The .cpp files can be handled very similarly to the .h files described
above.  You may use the same header template shown in the previous section
about .h files, and all the same guidelines apply.  

The principal difference is that it is not necessary to repeat the class
description placed in the .h file, nor indeed is it necessary to copy or
recreate the documentation of class methods.  As already mentioned, when
the API manual is generated by Doxygen, it will use the comments from the
.h file as the source of the documentation for the class and methods.

However, it @em is important to document @em functions, because these are
not defined by the .h files.  This is especially important for the C
wrappers around the C++ methods.  All the same documentation conventions
described so far apply to describing functions.  The following example
provides an illustration:
@verbatim
/**
 * Creates a new CompartmentType with the given @p id and @p name attribute
 * values.
 *
 * In SBML Level 2 and beyond, the identifier attribute of a
 * CompartmentType is required to have a value, but the name is optional.
 * Programs calling this function can legitimately use an empty string for
 * the @p name parameter.
 *
 * @param sid the value to assign as the identifier of this CompartmentType
 * @param name the value to assign as the name of this CompartmentType
 *
 * @return a pointer to the newly created CompartmentType_t structure.
 */
LIBSBML_EXTERN
CompartmentType_t *
CompartmentType_createWith (const char *sid, const char *name);
@endverbatim

@section coding-misc-doxygen Miscellaneous Doxygen notes

@li The doxygen command @c \@internal is (according to the doxygen
documentation) supposed to let you flag things as internal implementation
code, such that it is not put in the finished documentation.  This would be
great if we could use it, but I (MH) have been unable to make this work.
(Yes, there is a configuration flag, and yes, I've tried setting it both
ways.)



*/
