Isis 3 Documentation

Introduction | Mandatory Commands | Useful Commands | Example Header | Example Implementation | HTML Quick Reference

Introduction: Conventions and Definitions of this Guide

Purpose

This guide has been generated for Isis programming team as a style reference for writing in-code documentation to meet team requirements for consistency, content, and information dissemination. Serving as a reference for proper documentation structure for automatic generation of documentation in various formats, primarily HTML, is the primary focus of this guide. Isis Applications have their own code and documentation style. Information for the documentation system maintainers will be provided in a separate document covering system level tags (such as @mainpage and @defgroup), directory structure, naming conventions, etc.

Conventions

In the tag lists (later in this guide), arguments will be surrounded with either < >s, [ ]s, ( )s, or { }s. These brackets should not be included in the tags when used--they are only used as a visual reference in this document.

• Parentheses () will be used to mark titles and independent names for items,
• square brackets [] will be used to mark optional one word arguments,
• angle brackets <> will be used to mark keywords used by doxygen to identify members, and
• curly braces {} will be used to denote multi-worded descriptions.

Definitions

Mandatory is a pretty strong word... we will define here to mean use it if it applies. Many documentation components will always be included, such as CVS revision for files and category for classes. Other tags may not always be applicable, such as documenting return value and parameters for functions. Use your discretion, and have your documentation reviewed by a peer.

Top

Understanding Our Audience: API verses Programmer Reference

There are two major audiences for our source code documenation. Two sets of documentation are maintained, one for each audience.

• Application Developers: These folks only want to know how to use Isis objects. They use the API, which gives information about public and protected entities, new features, and descriptions and examples of usage. This audience will be encouraged to use the web pages for reading the API.
• Object Programmers: These folks are mainly the ones who maintain and develop Isis. This audience needs to know details about the inner workings of the code in order to maintain it. They use the Programmers' Reference, which provides all the verbose nitty gritty information, such as documentation for private entities, history, things to do, and other internal documentation. While this group will have verbose web-based documentation, they often read the documentation in the source code instead of going to the website.

Top

Naming Conventions

File Extensions:

• Header files have a .h extension.
• Implementation files have a .cpp extension.
• Plugin files have a .plugin extension.
• Truth files have a .truth extension.
• Primary make files are named Makefile. Secondary make files (called from the primary) should begin with the string Makefile.

Files and Directories

We will be using a UpperCamelCase syntax, where every new word begins with a capital letter, for all file names and most directory names.

Object Directories: All of an Object's files go into a directory named identically to the Object. In the case where the Object has several classes, one primary class (the parent, base, API) should be identified and used for naming the directory.

Subdirectories are not allowed for Object source code.

Files: Header and Implementation files are to name identically to the class they define. In the case where the file contains several classes, one primary class (the parent, base, API) should be identified and used for naming the file.

Naming user defined types and method names:

We will be using a UpperCamelCase syntax, where every new word begins with a capital letter, for all user defined types (classes, structs, typedefs, etc.), and method names, such as: ProcessByLine (class) and ProcessByLine() (constructor).

Naming variables:

All variables will use lowerCamelCase syntax, where the first letter is lower case and the beginning of other words are capitalized, such as: allRequirements.

Top

Documentation Basics

Source Code Documentation Structure

Currently, the Isis programming team is using the Doxygen documentation extraction software. Doxygen has extended the tag set of the javadoc documentation style, a systematic in-code documentation style that allows pertinent documentation to be extracted easily. Doxygen is just one of many software packages that are able to extract and use javadoc documentation for a variety of purposes, allowing us to take advantage of a wealth of documentation extractors, IDEs, and other tools on the market that make our lives simpler and more productive.

In order to be able to generate automatic documentation correctly and follow a systematic and consistent approach , each programmer must:

• Write documentation for each entity (class, method, struct, variable, etc.) in the source code where the primary or most commonly used definition of that entity resides. Generally, this means the following files contain documentation for the listed entities:
  • Header (.h): classes, inline functions, enums, typedefs, unions, structs, and variables declared in the header file
  • Implementation (.cpp): member function implementations and any entities declared or defined in the implementation file
• Use specialized commenting styles before or after each entity, called documentation lines or documentation blocks, for example:
  • Single line of documentation (documentation line)
    • start documentation with string //! before or //!< after the code
    • Before the entity
      //! my integer
      int myInteger ;
    • After the entity
      int myInteger ; //!< my integer
      
  • Multi-lined documentation (documentation block)
    • wrap documentation with /** */ before or /**< */ after the code
    • Before the entity

      /**
       * my method
       */
      int myMethod () {
        return myInteger ;
      }
                  

    • After the entity

      int myMethod () {
        return myInteger ;
      }
      /**<
       * my method
       */
                  

Top

Date Format

Dates should always follow the ISO date format standard. Generally, you'll want to note the current date - use YYYY-MM-DD. See the complete ISO 8601 standard [190KB PDF] for the complete information. Use of this standard allows us to avoid internationalization issues and have dates that can be easily extracted by computer software.

Top

Using HTML

HTML can be used anywhere in your documentation. Keep it simple. Doxygen will "interpret" your HTML, so you may not get the desired effect. Best advice, avoid attempting special effects by just using the basic HTML formatting tags - bold, underline, pre, code, table (caption, tr, td, th), etc. and only when really necessary. Better yet, consider using the formatting tags in the Other Useful Tags section instead of HTML. Your plain old text will be pretty nicely rendered into paragraphs with automatically linked items and other bells and whistles. Keep your source readable: minimize formatting.

Top

Autolinking

Class, method, variable, and other entity names will be automatically linked in the documentation. To prevent this for a specific occurence of a name, use a percent sign (%) in front of the name. For example, if you have a class name "Histogram" and you want to prevent the linking of the word "Histogram" in your description because it is not referring to the class but to an actual histogram, use "%Histogram" to prevent the word from being linked.

E-mail addresses and web addresses are also automatically linked. If a web address is particularly long, put it on its own line.

Top

Document History