Documentation Guide

In an attempt to present a consistent organization and style to the documentation, here are a list of conventions that should be followed for the User Guide and the Tutorial. For more information on creating Tutorials, please see Writing a Tutorial

Doxygen-Generated Documentation Style Guide

• When referring to file folders/directories, use the word 'directory'

• When referring to code snippets, use the \code and \endcode tags.

• Use the <tt> and </tt> tags when referring to specific files or directories.

• When referring to commands that should be typed at the command line, use the \code and \endcode tags and also place the corresponding shell symbol in front of the command. For example:

  • Use '$' for non-root Linux/OS X users at the command line.
  • Use '#' for root Linux/OS X users at the command line.
  • Use '>>' for MATLAB users at the MATLAB command prompt.

• The title of each chapter, section, subsection, and subsubsection should include the correct tag, a unique identifier, and a human-readable string of the form:

  • For chapters: \page ch1_getting_started Chapter 1: Getting Started
  • For sections: \section ch1s1_preinstallation 1.1 Pre-Installation
  • For subsections: \subsection ch7s1s1_setting_up 7.1.1 Setting Up a Spike Monitor
  • for subsubsections: \subsubsection ch7s1s2s1_start_stop_recording 7.1.2.1 Start and Stop Recording

• At the beginning of each sub-chapter (e.g., 3.1, but not for every 3.1.1, 3.1.2, etc.), put \author Name of Author 1 \author Name of Author 2

• At the end of each sub-chapter, list other related topics with \see \ref ch5s4_neuromodulation \see CARLsim::someMethod

• At the very end of each sub-chapter, if the described functionality is new, put a tag stating the minimum CARLsim version that supports the described functionality: \since v2.1

• Tip: How to reference enums, structs, and struct fields so that doxygen will link to the corresponding code: ::INHIBITORY_NEURON ::carlsimState_t ::EXE_STATE