libSBML Perl API
libSBML 5.8.0 Perl API
|
The following is a collection of guidelines for libSBML authors and other interested persons to follow when writing libSBML code and documenting it.
General guidelines Summary of commonly-used Doxygen commands in libSBML Guidelines for documenting .h files Guidelines for documenting .cpp files |
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 Doxygen, 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.
@
or \\
. Since it doesn't matter which, we may as well use the @
form because it's also used by Javadoc (and thus is easier to remember for Java programmers). *
) characters, as in the following example: /** * Comments within which commands for Doxygen begin with the character @. */If your comment does not begin with
/**
, then it will be ignored by Doxygen. This can be either bad or good, depending on the intention behind the comment. /** * creates a foo object * given arg is the template */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.
%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. /** * 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. */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:
/** * This is the brief description. * * This is the beginning of the detailed description.... */The visual split makes it really obvious what's going to happen.
/** @cond doxygen-libsbml-internal */at the beginning and
/** @endcond doxygen-libsbml-internal */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.)
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 Doxygen website.
Command | Meaning | |
@file | Defines the name of the current file. | |
@brief | Provides a one-sentence description of the entity being described (a file, a class, etc.). | |
@author | Names the author of the entity being described (a file, a class, etc.). | |
@c | Puts the following word in typewriter ("code") font. To style more than one word, use <code>the words</code> . If you need to put something that contains HTML tags in typewriter font, use the <code>the words</code> form, and use the HTML character codes < and> to embed the openening '<' and '>' characters inside the words . | |
@em | Puts the following word in italic font, for emphasis. To put multiple words in italics, use <em>the words</em> . | |
@n | Forces a newline, like HTML's <br> . | |
@p | Puts the following word in typewriter ("code") font. This form is preferred when the word is a parameter to a method or function. | |
@li | Starts (or continues) a bullet list. You can insert the first @li in a comment, and the item will continue until a paragraph break or the next @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 @li command. | |
@class | 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). | |
@param | Declares a parameter to a method or function. The first word following @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. | |
@return | Declares the return value from a method or function. | |
@see | Formats a reference to another entity in the documentation. Commonly used to refer to related classes or methods. | |
@note | 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 @note blocks at the end of a documentation block, for uniformity in the API documentation. | |
@warning | 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 @warning blocks at the end of a documentation block, for uniformity in the API documentation. | |
@bug | 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 @bug blocks at the end of a documentation block, for uniformity in the API documentation. |
Many HTML commands will work in comments for Doxygen. For example, a common one is the a
tag for linking text to a URL, as in <a href="http://sbml.org">home page</a>
.
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.
/** * @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 2005-2010 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 *----------------------------------------------------------------------- -->*/Of course, you should substitute appropriate content where the text is following is an complete example taken from an actual libSBML file at the time of this writing:
/** * @file Compartment.h * @brief The libSBML class of object implementing SBML's Compartment. * @author Ben Bornstein * * *<!--------------------------------------------------------------------------- * This file is part of libSBML. Please visit http://sbml.org for more * information about SBML, and the latest version of libSBML. * * Copyright 2005-2010 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 ...
/** * The libSBML class implementing SBML's CompartmentType construct. * * CompartmentTypes in SBML are ... */ class LIBSBML_EXTERN CompartmentType : public SBase { public: ...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
#ifdef __cplusplus
, 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, please put the documentation in the file header 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): /** * @file CompartmentType.h * @brief Definitions of CompartmentType and ListOfCompartmentTypes. * @author Ben Bornstein * *<!--------------------------------------------------------------------------- * This file is part of libSBML. Please visit http://sbml.org for more * information about SBML, and the latest version of libSBML. * * Copyright 2005-2010 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 ...
@return
to describe the returned value; if it takes parameters, use @param
to describe the parameters. If you also need to refer to the parameters in the textual description of the method, use the @p
command. The following example illustrates this: /** * 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 = "");
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);
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 is important to document 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:
/** * 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);
@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.)