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

@section coding-toc Table of contents

@htmlinclude doxygen-regular-text-start.html
<table border="0" class="centered">
<tr><td style="font-size: small;">
@ref coding-intro @n
@ref coding-basic @n
@ref coding-docs @n
@ref coding-other-situations @n
@ref coding-doxygen-summary @n
@ref coding-doc-toolchain @n
@ref coding-misc-doxygen @n
</td></tr>
</table>
@htmlinclude doxygen-regular-text-end.html


@section coding-intro 1. Introduction

This document is a collection of guidelines for libSBML authors to follow
when writing libSBML code and documenting it.

LibSBML's application programming interface (API) is documented using a
combination of tools.  For almost all languages (C++, C#, C, Python, and
others), the cornerstone of the approach is the open-source software tool <a
href="http://www.doxygen.org">Doxygen</a>; for Java, we use Javadoc instead.
We write the documentation in source code and auxiliary files in a way that
both Javadoc and Doxygen can process or more less equally, which requires
that programmers and documentation authors follow various conventions
described in the rest of this document.  In addition, we use various
home-grown scripts and programs to massage the output of SWIG to produce
something that can be fed to the Doxygen and Javadoc-based toolchains.  


@section coding-basic 2. Basic guidelines for writing libSBML documentation

The guidelines presented in this section are oriented towards explaining how
to organize code comments such that Doxygen and Javadoc can produce good
output, yet simultaneously make the comments in the libSBML code be readable
on their own.

@li Doxygen keywords/tags can be prefixed with either @c \@ or @c @\\, but
Javadoc keywords can only be prefixed with @c \@.  Always use the @c \@ prefix
for keywords so that they will be understood by both Doxygen and Javadoc.
@li The main types of 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 understood by Doxygen will begin
 * with the character @.
 */ 
@endverbatim
Another type of Doxygen comment, used to document enumeration members, begins
with <code>/*!&lt;</code>.  If your code documentation does @em not appear
inside a comment block that begins with <code>/**</code> (or the more
rarely-needed <code>/*!&lt;</code>), then it will be ignored by Doxygen.
This may or may not be what you want, depending on the intention behind the
comment.
@li Doxygen comment blocks can appear at the beginning of a file, in front of
a class declaration, in front of method declarations, in front of function
declarations, and in front of data structure definitions.
@li Doxygen reads both <code>.h</code> and <code>.cpp</code> files.  In the
case of C++ code, there is a critical difference in how it constructs the
final output from these files.  The contents of a <code>.h</code> file takes
precedence over the contents of the corresponding <code>.cpp</code> file;
however, if a class member (i.e., a method or data member) has
<code>/**</code> comment blocks in both the <code>.h</code> and
<code>.cpp</code> files, they are @em combined in the final output.  This
frequently leads to duplicate text in the final output.  To avoid this, and
to simplify maintenance of documentation, only document the C++ code in the
<code>.h</code> files.  However, and confusingly, <em>C functions must be
documented in the <code>.cpp</code> files</em>.  Thus, the rule is:
<strong>document classes in <code>.h</code> files, but document C functions
in the <code>.cpp</code> files and not the <code>.h</code> files</strong>.
@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 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 in the source makes it more obvious what's going to happen.
@li 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 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 doxygenLibsbmlInternal */
@endverbatim
at the beginning and 
@verbatim
/** @endcond */
@endverbatim
at the end of the block.  (Explanation: this sets up a conditional that
will only be "seen" by Doxygen if the symbol "doxygenLibsbmlInternal" is
defined.  Since it's never defined in the Doxygen configuration, 
the block will be ignored.)
@li Do not use \@retval for describing return values; instead, use \@return
because (1) it is what Javadoc uses and (2) the narrative form of \@return
lets you provide more contextual information and other details in describing
the return value(s) of a method or function.
@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 Please write sentences with @em two (2) spaces after the terminating
period, not one.  This makes the resulting text easier to read during
editing, compared to when sentence-ending periods are followed by only one
space.  (This issue concerns the readability and editability of source code,
not the apperance of rendered output.  The finished typeset output will @em
not have two spaces after every sentence-ending period; it will have one or
slightly more than one, depending on the output format produced.  The reason
two-spacing is important for the source is that most people use monospaced
fonts in their text editors and IDEs, and when using monospaced fonts, the
ends of sentences are much easier for human eyes to pick out when two-spacing
is used.  Further, text editing programs such as Emacs and vi have special
features to recognize sentences based on this pattern, and proficient users
of those editors can make use of sentence-oriented editing commands.)


@section coding-docs 3. Guidelines for different file types

Below are explanations of how to write documentation for the most common
types of files encountered in libSBML.


@subsection coding-doc-h 3.1 Guidelines for .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
<code>.h</code> file for libSBML (and in fact, it's the same for
<code>.cpp</code> files, too).  Of course, you should substitute appropriate
content for the text in square brackets (@c [ and @c ]) below:
@verbatim
/**
 * @file    [filename]
 * @brief   [succinct description of what's in this file]
 * @author  [author's name]
 * 
 *<!---------------------------------------------------------------------------
 * This file is part of libSBML.  Please visit http://sbml.org for more
 * information about SBML, and the latest version of libSBML.
 *
 * Copyright (C) 2009-2013 jointly by the following organizations: 
 *     1. California Institute of Technology, Pasadena, CA, USA
 *     2. EMBL European Bioinformatics Institute (EBML-EBI), Hinxton, UK
 *  
 * Copyright (C) 2006-2008 by the California Institute of Technology,
 *     Pasadena, CA, USA 
 *  
 * Copyright (C) 2002-2005 jointly by the following organizations: 
 *     1. California Institute of Technology, Pasadena, CA, USA
 *     2. Japan Science and Technology Agency, Japan
 * 
 * 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
@li When more than one author should be acknowledged for a given file, use 
multiple <code>@@author</code> entries, one per line.
@li A <code>.h</code> file will typically have a class declaration in it.
The @em normal way that one would document the class (but we do not do it
this way) is to put a comment block immediately in front of the class
declaration.  Unfortunately, we are hit here by the problem of how to
generate descriptions for different programming languages from the same
source files.  In particular, those class declarations in the <code>.h</code>
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, <strong>please put the documentation in the file header rather that
ahead of the class itself</strong> in the file.  The following example
illustrates this procedure (and note how more than one class can be described
in the header):
@verbatim
/**
 * @file    Compartment.h
 * [...]
 *
 * @class Compartment
 * @ingroup Core
 * @brief Implementation of SBML's %Compartment construct.
 *
 * A compartment in SBML represents a bounded space in which species are
 * located.  Compartments do not necessarily have to correspond to actual
 * ....
 * 
 * <!-- leave this next break as-is to work around some doxygen bug -->
 */ 
/**
 * @class ListOfCompartments
 * @ingroup Core
 * @brief Implementation of SBML Level&nbsp;2's %ListOfCompartments construct.
 * 
 * The various ListOf___ classes in SBML are merely containers used for
 * ....
 */

#ifndef Compartment_h
#define Compartment_h
...
@endverbatim
@li Use the <code>@@ingroup</code> to indicate the SBML Level&nbsp;3 package
to which a class belongs.  Place the keyword immediately on the line after
the <code>@@class</code> declaration in the <code>.h</code> file. For
example, <code>@@ingroup layout</code> would indicate that the associated
class is part of the SBML Level&nbsp;3 <em>%Layout</em> package.  The code
<code>@@ingroup core</code> should be used for SBML Core code.
@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 takes parameters, use @c \@param to describe the
parameters.  If it's a method and the method returns a value, also use @c
\@return to describe the returned value.  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. Here is an example taken
from a class definition in a <code>.h</code> 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);
@endverbatim


@subsection coding-doc-cpp 3.2 Guidelines for .cpp files

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

The principal difference is that it is not necessary to repeat the class
description placed in the <code>.h</code> 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 <code>.h</code> 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 <code>.h</code> 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-other-situations 4. How to handle important common situations

The descriptions above cover the basics of using Doxygen and Javadoc for
libSBML documentation.  What follows is a discussion of other, more involved
topics.

@subsection coding-reusing-text 4.1 Reusing common text

One often encounters the need to repeat the same text in different places in
the documentation, such as to add a detail to each method where the detail
may be relevant.  In software documentation, unlike in non-technical prose or
creative writing, it is better to repeat text&mdash;or refer to a common
section&mdash;everywhere that it might be relevant, because a reader does not
normally read class and method documentation linearly; they jump to a method
description from elsewhere, and so the method description needs to contain
the details or point the reader to another source directly.  However,
copy-pasting documentation text leads to a maintenance nightmare because any
updates or changes must be made in multiple places.




@subsection coding-links 4.2 Links

Most of the time, you can rely on Doxygen's ability to connect a written
reference to a class or method to the definition of that class or method.  In
a few cases, you must write an explicit <code>@@link</code>
... <code>@@endlink</code> command.  The syntax of this Doxygen command
consists of the target of the link, optionally followed by a name to be used
for the link.

In libSBML, the most common situation where an explicit link is needed is in
references to enumeration values such as method/function return codes.  In
those cases, to create a link, use the name of the enumeration (e.g.,
<code>OperationReturnValues_t</code>), followed by a pound sign (@c #),
followed by the enumeration member, optionally followed by a space and then a
name for the link.  If the optional space and name are omitted, the name of
the link is made the same as the target; this is generally @em not desirable
because the result is more difficult to read.

Here is an example, drawn from the documentation of the return type of a
method on the Compartment class.  In these cases, the name of the link is
given as simply the name of the enumeration member without the enumeration
prefix:
@verbatim
/**
 * Sets the value of the "id" attribute of this Compartment.
 *
 * The string @p sid is copied.  Note that SBML has strict requirements
 * for the syntax of identifiers.  @htmlinclude id-syntax.html
 *
 * @param sid the string to use as the identifier of this Compartment
 *
 * @return integer value indicating success/failure of the
 * function.  The possible values returned by this function are:
 * @li @link OperationReturnValues_t#LIBSBML_OPERATION_SUCCESS LIBSBML_OPERATION_SUCCESS @endlink
 * @li @link OperationReturnValues_t#LIBSBML_INVALID_ATTRIBUTE_VALUE LIBSBML_INVALID_ATTRIBUTE_VALUE @endlink
 */
virtual int setId (const std::string& sid);
@endverbatim

Another situation that calls for explicit links involves the non-C++
languages.  There, it is common to need to refer to a constant defined on the
class or package <code>libsbml</code>.  Here is an example:
@verbatim
* @if python LibSBML attaches an identifying
* code to every kind of SBML object.  These are known as <em>SBML type
* codes</em>.  In the Python language interface for libSBML, the type
* codes are defined as static integer constants in the interface class
* @link libsbml@endlink.  
@endverbatim


@subsection coding-conditionals 4.3 Conditional text

Speaking of non-C++ languages, it very often happens that one needs to adapt
the documentation for something based on the programming language.  


@subsection coding-common-text 4.4 Warnings and other notes

@subsection coding-figures 4.5 Figures



@section coding-doxygen-summary 5. 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-toolchain 6. The documentation-generation toolchain and procedures

The following diagram illustrates the overall processes used for generating
the libSBML documentation.

<em>Forthcoming...</em>


@section coding-misc-doxygen 7. 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.)



*/
