dddoc
The documentation system "dot-dot-doc".
Seqan uses its own documentation system, called "dot-dot-doc", or shortly "dddoc". This document describes the documentation system.
1 General principles
The documentation can be viewed as a tree and is distributed over several files. The files are either special dddoc files (ending in .dddoc) or C++ source code files. (This page was written in a dddoc file). In C++ source code files one can introduce documentation by using the special comments /** or ///. The documentation is generated by a python script that searches all files for documentation commands and builds from this a coherent documentation in HTML (for later a Pdf documentation is planned).
In the development environment, the documentation is built by calling "make.bat" (Windows) or "make.sh" (Linux) in the "docs" directory. In both cases optional arguments specify which modules are built, i.e. which subfolder of "application/library" should be scanned for documentation. If no modul is specified then the complete documentation is built. In order to build only the pages residing under "docs" one can specify as modul name "static" (or any other name that is not a real modul). Note that indexes and menus are only created when the entire documentation is built, or if "indexonly" is specified instead of a real module name.
SeqAn is released with the complete documentation and the release does not include the dddoc python scripts.
Files that contain the string "SEQAN_NO_DDDOC" are not scanned for documentation, i.e. all documentation in the file is ignored.
2 Notation
The documentation is stored as a dddoc tree. Each node of this tree has a name. The path from the root to another node in the tree is given by enumerating the corresponding names of all nodes on the path separated using a ".". For example "animals.pets.dogs.wuffi". Each node in a dddoc tree also contains one or more (possibly empty) pieces of text.
The dddoc tree is defined by a set of entries. Entries have the form ".[Path]:[Text]", while [Path] describes a node in the dddoc tree and [Text] a piece of text associated to that node. Each entry has to start in a new line, that means the first character in the line is ".". The text piece [Text] can span over multiple lines as long as these lines does not begin with a "." character. If [Path] does not start with a dot, then it represends a complete path from the root of the ddoc tree to a node. If [Path] starts with n dots, then it is interpreted as a sub-path to the closest preceding entry with a [Path] starting with n-1 dots. Informally spoken: "." plays the same role in dddoc as tabs in python.
Example 1
.animals.pets
..dogs.my_dog
...name:Snoopy
...age:5
..cats.my_cat
...age:2
The above is the same as:
.animals.pets.dogs.my_dog.name.Snoopy
.animals.pets.dogs.my_dog.age:5
.animals.pets.cats.my_cat.age:2
Example 2
.address.name:Andreas Döring
..comment:That is a comment,
 which contains several lines.
..comment:This will be another comment.
Example 3
.Domainen."www.seqan.de":The SeqAn Homepage
For clarification, we list here some terms that are used in this text:
entityA part of the documented C++ code, e.g. a class or a function.
entrySmallest meaningful part of documentation: Specifies a node within the dddoc tree and a piece of text for this node.
itemA part of the documentation, e.g. the documentation of an entity.
fieldPart of an item.
subfieldPart of a field.
3 Entries
The documentation consists of a set of items. For each C++ entity that is documented exists one item. The path of an item has the form "[Category].[Name]", i.e. items correspond to subtrees of the dddoc tree and the roots of this subtrees have depth 2.
The text associated to the root node of an item is used as a description text, but it is encouraged to use text fields instead. If several entries define text pieces for an item, these text pieces are concatenated.
3.1 Categories
At the moment, dddoc supports the following item categories:
"Page"general content, e.g. tutorials etc.
"Concept"concepts
"Class"classes
"Spec"specializations
"Shortcut"shortcuts
"Function"(global) functions
"Memfunc"member functions
"Memvar"member variables
"Metafunction"meta functions
"Tag"tag
"Adaption"adapters
"Demo"examples programs
In addition dddoc supports the following technical categories:
"Internal"is used to document internal entities that should not belong to the official documentation of the library. Hence it is forbidden to introduce links from or to this category.
"globals"stores meta information and constants that are used for the generation of the documentation. In addition it is used to define index pages for the individual categories.
Sub-categories are specified using the "cat" field, see below.
3.2 Names
The name of a category subnode is usually the name of the entity that is documented by this item, e.g. the C++-Function "length" is documented in the item "Function.length". If it is desired, another name can be displayed by using the "title" field, see below.
If the name contains a "#" character, then only the string after the (first) "#" character is displayed. This should be used for Memfunc and Memvar items: write the class name in front of the "#" and the member name after it. Instead of the "#" character the "|" character can also be used.
4 Fields
Fields define the properties of an item. In the dddoc tree, fields are subnotes of items. A field has therefore the form "[Category].[Name].[Field]":
4.1 Special fields
"title"title of the page (optional). Default is [Name]. Text pieces defined by several entries for the same "title" field are concatenated.
"summary"Short summary of the item. Each item should have exactly one summary, otherwise a warning is displayed. Place longer descriptions under "remarks" or "description". Text pieces defined by several entries for the same "summary" field are concatenated.
"cat"subcategory. The text appears in the documentation in a subfolder of [Category]. Sub-subcategories can be defined by a "."-separated category path, e.g. "cat:animal.rodents.hamsters". each item can possess several subcategories. In this case the tex appears in all corresponding subfolders.
"signature"Isolated piece of code that demonstates the use of the item. for example: "length(container)"
"file"displays the source file if given the path to a .cpp file. Should be used only for demos. All lines in the source file that start with a dddoc comment (e.g. "///") are displayed as an ordinary C++ comments.
"hidefromindex"Exlude item from indexes and menus. A page for this
"order"the string is used instead of [Name] for sorting the items in indexes and menus. Please note that numbers are parsed as text, hence the entry "order:10" will be placed in front of "order:2".
4.2 Text fields
Fields that define texts. The text can be structured using subfields. Text pieces defined by several entries for the same text field are concatenated.
"description"descriptive text. Can be used for tutorials.
"example"code examples.
"include"name of header file you have to include to use the entity.
"output"the output of a program. "code" subfields of this field will be displayed in a special console like style.
"remarks"comments.
"returns"return value. If several return values are given, the subfield "param" should be used after "return".
4.3 Tables of text fields
Child nodes below a table field are sorted alphabetically and printed in form of a table of text fields.
"param"argument. e.g. "param.length:length of a field". If a param does not appear in one of the item's signatures, a warning is displayed.
"value"Possible value an entity can take.
"tag"Possible tag type.
"glossary"Glossary entry. Glossary entries are displayed in alphabetic order. Should only be used in special glossary pages like Page.Glossary.
4.4 Link fields
Link to other items. Most link fields automatically generate back links by creating new fields for the target item. E.g. "Class.doc.base:Class.animal" creates a field "Class.animal.derived:Class.doc".
"base"link to class or spec. If Class or Spec: The base class. (inserts back link: "derived")
"baseconcept"link to a concept. Using Concept: the current item is a child concept that inherits all properties from the specified base concept, i.e. a class that implements the child concept also implements the base concept. (inserts back link: "childconcept")
"class"link to class or spec. Using Memfunc or Memvar: name of the class belonging to the item. (inserts links "memfunc" or "memvar")
"concept"link to concept. A class that implements this concept must implement the current item. Do not disturb with "implements". Insert back link depending on the current item's category.
"demo"link to a demo. Demo explains how to use the item. (inserts back link "demofor")
"general"for Spec: The correspnding class. (inserts back link "spec")
"implements"link to concept that is implemented by the current item. Do not disturb with "concept". (inserts back link "conceptimplements")
"see"crossreference to another item. (inserts back link "see").
"shortcutfor"link to another item, for which the current item is a shortcut for. (inserts back link: "shortcut")
In addition, there are the following link fields. However, we discourage the user of dddoc to use them, since these links can be set with the link field commands mentioned above:
"childconcept"link to "baseconcept"
"conceptfunc" link to "concept"
"conceptimplements"link to "implements"
"conceptmemfunc" link to "concept"
"conceptmemvar" link to "concept"
"conceptmetafunc" link to "concept"
"conceptusedby" link to "concept"
"demofor"for demo: link to an item in a demo. (inserts back link "demo")
"derived"for class or spec: A specialisation.
"function"For class or spec: a function (is inserted as link by using "param.[Name].type", "returns.type" or "returns.[Name].type" in function
"memfunc"for class or spec: A member function.
"memvar"for class or spec: A member variable.
"shortcut"link to shortcut. (inserts back link "shortcutfor")
"spec"for class or spec: A specialisation.
"type"for class or spec: A meta function (is inserted as link by using "param.[Name].type" in Metafunktion
5 Subfields
children nodes below text fields.
5.1 Free subfields
Free subfields are output in the order they appear in the sources. All other subfields are collected and displayed unter the corresponding subsection heading.
"section"inserts new section heading. The first occurence of the "#" character is replaced by a section number. example: "..section:#. My chapter"
"subsection"inserts heading for new subsection. If the heading contains exactly one "#" character then it is replaced by the subsection number. Otherwise the dirst "#" character is replaced by the section number and the second "#" character by the subsection number. examples: "..subsection:#.# Subsection", "..subsection:Example #"
"contents"builts a table of contents in which all sections and subsections of this field are displayed.
"text"a text paragraph.
"note"an emphasized text paragraph.
"code"example code.
"output"output of a program, displayed in a console like style.
"image"Inserts an image. Needed is the name (optinally with a relativ path) of the image (without extension). If the documentation is constructed in HTML then the extension ".png" is automatically appended. Note that there should also be an ".eps" version of the image for LaTeX exports in the future.

Images should be stored in the "img" folder. Optionally a caption can be given by using the"|" command. e.g. "..image:seqan_logo_large| This is the large SeqAn logo.". Should more images appear next to each other then one can specify the additional images with more "|" commands, e.g. "..image:file1|caption1|file2|caption2|file3|caption3".

"table"displays a row of a table. The columns are separated using the "|" command. Subsequent "table" and "tableheader" subfields are put together in one table.
"tableheader"displays an emphasized table row (the columns contain the header text).
"field"displays a part of the documentation of another item, i.e. one field of this documentation. For example "field:Class.String.spec" displays a list of all specializations of the item "Class.String". Note that this will generate redundancy, since the same information will be printed on the documentation page for "Class.String". Consider to use a link to that item instead.
5.2 Text Subfields
Text pieces defined by several entries for the same text subfield are concatenated.
"value"a value.
"default"default value.
"remarks"commentary or code.
5.3 Tables of text subfields
"param"list of parameters. Is used in conjunction with "returns" to list different return values.
5.4 Link subfields
Link subfields link to other pages. To disable linking, use "nolink:" as a prefix. For example, write "..type:nolink:unsinged int" to state that the type for a given param or return field is unsigned int.
"metafunktion"link to a meta function. For "param" or "return" fields e.g. to the meta function that yields the typ of the arguments or of the return values.
"type"link to a type (class, spec oder adapter). For "param" or "return" fields for example the type of the arguments or of the return value (inserts link: "function" function, "type" for meta functions.)
"concept"link to a concept. Using in "param" fields: A concept that must be implemented by objects that are used as arguments. (inserts link: "conceptusedby")
"see"link to another item. (does not insert back link)
6 Formatting text
We allow LaTeX special characters in text (not in ID strings). e.g. \Sigma, \in and \leftarrow produce the characters Σ, Î resp. ←. In this manner also european special characters can be inserted. One can also use command characters reserved in dddoc. For example \dot, \quote, \at, \pipe, \dollar and \backslash produce ., ", @, |, $ and \. A list with all available characters can be found in dddoc_html_trans.py.
Other possibilities to special characters: \\ stands for \, $$ for $.
\br inserts a manual line break.
If C++ code should be displayed within a text field or subfield, it should be placed between $, e.g.: $int x$ yields: int x.
7 Links
Links to entries are written as follows: "[Category].[Name]", e.g. "Class.String" gives: "String". Links to the overview page of a category as follows: "[Category]", e.g. "Metafunctions". Links to external URLs start with "http:" or "ftp:", e.g. "http://www.seqan.de".
Links to glossary entries start with "glos:", e.g. "glos:Concept" gives: "Concept". Note that if there is no glossary entry that matches exact to the given string, an inexact search is performed, e.g. "glos:Concepts" and "glos:concept" will both refer to the entry "glos:Concept".
A link can also be turned back into a non-link by writing "nolink:" in front of it, e.g. "type:nolink:unsigned int".
If another text should be displayed fr the link it can be appended using the "|" character, e.g. "Class.String|the string classe" erzeugt: the string class. or "http://www.seqan.de|Link to SeqAn Homepage" gives: Link to SeqAn Homepage. Optionally one can also write the display text of a link to an item after an additional "." instead of a "|".
Within a text field/subfield one can insert links by placing them between @ characters, e.g. "click @Class.String.here@!" gives: click here!
SeqAn - Sequence Analysis Library - www.seqan.de
 

Page built @2014/08/13 16:19:46