# Class ToolDoc
Container for string documentation on a command line tool.

Implements | AssignableConcept
All Impl'd | AssignableConcept
Defined in | <seqan/arg_parse.>
Signature | `class ToolDoc;`

## Member Function Overview

- `ToolDoc::ToolDoc()`
  Constructor

### Member Functions Inherited From AssignableConcept

- `operator=`

## Interface Function Overview

- `void addListItem(toolDoc, key, value);`
  Add a list item to a ToolDoc.
- `void addSection(toolDoc, title);`
  Add a section with the given title.
- `void addSubSection(toolDoc, title);`
  Add a subsection with the given title.
- `void addText(toolDoc, text[, isParagraph]);`
  Add a text line/paragraph to ToolDoc.
- `void append(a, b);`
  Append two ToolDoc objects.
- `void clearEntries(toolDoc);`
  Clear entries from ToolDoc.
- `CharString getCategory(toolDoc);`
  Get the tool category.
- `CharString getDate(toolDoc);`
  Get the date.
- `CharString getManTitle(toolDoc);`
  Get the tool man page title of.
- `CharString getName(toolDoc);`
  Get the tool name.
- `CharString getShortDescription(toolDoc);`
  Get the tool short description.
- `CharString getVersion(toolDoc);`
  Get the tool version string.
- `void print(stream, toolDoc, format);`
  Print ToolDoc object in a given format.
- `void setName(toolDoc, name);`
  Set the tool name.
- `void setName(toolDoc, str);`
  Set the date string.
- `void setTitle(toolDoc, title);`
  Set the man title.
- `void setName(toolDoc, name);`
  Set the tool name.
- `void setShortDescription(toolDoc, text);`
  Set the tool short description.
- `void setName(toolDoc, str);`
  Set the tool version string.

### Interface Functions Inherited From AssignableConcept

- `assign`
- `set`
- `move`

## Detailed Description

### Remarks

This class is generally not used directly by the user but through ArgumentParser. It allows to store and represent all information related to a command line tool that would normally go into a man page. It can be printed to STL streams in different formats, currently plain text, HTML and man pages are supported.

You can also use basic formatting in text. This formatting is tailored to the usage on the command line. Use `\fB` to start bold font, `\fI` to start italic font and `\fP` to use the previous font (of course, use correct escaping of the backslash in C strings, so use `"\\fB"`, `"\\fI"`, and `"\\fP"` in your code.

### Examples

The following shows a brief example of how to use ToolDoc.

    ToolDoc doc;
    setName(doc, "RazerS");
    setShortDescription(doc, "Read mapping with controllable sensitivity.");
    setDate(doc, "04 March 2012");
    setVersion(doc, "1.0");
    setCategory(doc, "Read Mapping");
    setManTitle(doc, "SeqAn Apps Reference Manual");

    addSection(doc, "Synopsis");
    addText(doc, "\\fBrazers\\fP [\\fIOPTIONS\\fP] \\fIREFERENCE\\fP \\fIREADS\\fP", false);
    addText(doc,
            "\\fBrazers\\fP [\\fIOPTIONS\\fP] \\fIREFERENCE\\fP \\fILEFT_READS\\fP "
            "\\fIRIGHT_READS\\fP", false);

    addSection(doc, "Description");
    addText(doc,
            "RazerS is a read mapper with controllable, sensitivity.  This "
            "means that you can find all read matches in the reference sequence "
            "and optionally, you can trade lower sensitivity for better "
            "performance.");
    addText(doc,
            "What's special about RazerS is that you can control the sensitivity.");

    addSection(doc, "Options");
    addSubSection(doc, "Main Options");
    addListItem(doc, "\\fB-id\\fP, \\fB--indels\\fP",
                "Enable mapping with indels enabled.");
    addListItem(doc, "\\fB-i\\fP, \\fB--identity\\fP \\fIIDENTITY\\fP",
                "Set minimal identity of matches to find.");

    print(std::cout, doc, "text");

## See Also

- ArgumentParser
- addListItem
- addText

## Member Functions Detail

### `ToolDoc::ToolDoc()`

Constructor

#### Data Races

Thread safety unknown!

## Interface Functions Detail

### `void addListItem(toolDoc, key, value);`

Add a list item to a ToolDoc.

#### Parameters

`toolDoc` | The ToolDoc object to add the list item to.
`key` | The key for the list (CharString).
`value` | The value for the list (CharString).

#### Data Races

Thread safety unknown!

### `void addSection(toolDoc, title);`

Add a section with the given title.

#### Parameters

`toolDoc` | The ToolDoc object to add a section for.
`title` | The section title (CharString).

#### Data Races

Thread safety unknown!

### `void addSubSection(toolDoc, title);`

Add a subsection with the given title.

#### Parameters

`toolDoc` | The ToolDoc object to add a subsection for.
`title` | The subsection title (CharString).

#### Data Races

Thread safety unknown!

### `void addText(toolDoc, text[, isParagraph]);`

Add a text line/paragraph to ToolDoc.

#### Parameters

`toolDoc` | The ToolDoc to add the text to.
`text` | The text to add (CharString).
`isParagraph` | Whether to insert as paragraph or just a line (only one line break if not a paragraph).

#### Data Races

Thread safety unknown!

### `void append(a, b);`

Append two ToolDoc objects.

#### Parameters

`a` | This object is updated
`b` | This object is appended to `b`.

#### Data Races

Thread safety unknown!

### `void clearEntries(toolDoc);`

Clear entries from ToolDoc.

#### Parameters

`toolDoc` | The ToolDoc object to clear entries from.

#### Data Races

Thread safety unknown!

### `CharString getCategory(toolDoc);`

Get the tool category.

#### Parameters

`toolDoc` | The ToolDoc object to the get the category for.

#### Returns

`CharString` | Resulting category (CharString).

#### Data Races

Thread safety unknown!

### `CharString getDate(toolDoc);`

Get the date.

#### Parameters

`toolDoc` | The ToolDoc object to the get the date from.

#### Returns

`CharString` | Resulting date string (CharString).

#### Data Races

Thread safety unknown!

### `CharString getManTitle(toolDoc);`

Get the tool man page title of.

#### Parameters

`toolDoc` | The ToolDoc object to the get the man page title.

#### Returns

`CharString` | Resulting man page title (CharString).

#### Data Races

Thread safety unknown!

### `CharString getName(toolDoc);`

Get the tool name.

#### Parameters

`toolDoc` | The ToolDoc object to the get the name for.

#### Returns

`CharString` | Resulting name (CharString).

#### Data Races

Thread safety unknown!

### `CharString getShortDescription(toolDoc);`

Get the tool short description.

#### Parameters

`toolDoc` | The ToolDoc object to the get the short description for.

#### Returns

`CharString` | Resulting short description (CharString).

#### Data Races

Thread safety unknown!

### `CharString getVersion(toolDoc);`

Get the tool version string.

#### Parameters

`toolDoc` | The ToolDoc object to the get the version string.

#### Returns

`CharString` | Resulting version string (CharString).

#### Data Races

Thread safety unknown!

### `void print(stream, toolDoc, format);`

Print ToolDoc object in a given format.

#### Parameters

`stream` | The `std::ostream` to write to.
`toolDoc` | The ToolDoc to print.
`format` | The format, one of {"html", "man", "txt"}.

#### Data Races

Thread safety unknown!

### `void setName(toolDoc, name);`

Set the tool name.

#### Parameters

`toolDoc` | The ToolDoc object to the set the name for.
`name` | The name of the tool (CharString).

#### Data Races

Thread safety unknown!

### `void setName(toolDoc, str);`

Set the date string.

#### Parameters

`toolDoc` | The ToolDoc object to the set the date string for.
`str` | The date string of the tool (CharString).

#### Data Races

Thread safety unknown!

### `void setTitle(toolDoc, title);`

Set the man title.

#### Parameters

`toolDoc` | The ToolDoc object to the set the title for.
`title` | The title of the tool (CharString).

#### Data Races

Thread safety unknown!

### `void setName(toolDoc, name);`

Set the tool name.

#### Parameters

`toolDoc` | The ToolDoc object to the set the name for.
`name` | The name of the tool (CharString).

#### Data Races

Thread safety unknown!

### `void setShortDescription(toolDoc, text);`

Set the tool short description.

#### Parameters

`toolDoc` | The ToolDoc object to the set the short description for.
`text` | The short description of the tool (CharString).

#### Data Races

Thread safety unknown!

### `void setName(toolDoc, str);`

Set the tool version string.

#### Parameters

`toolDoc` | The ToolDoc object to the set the version string for.
`str` | The version string of the tool (CharString).

#### Data Races

Thread safety unknown!

#### Dox Sources

    /*!
     * @class ToolDoc
     *
     * @implements AssignableConcept
     *
     * @headerfile <seqan/arg_parse.>
     *
     * @brief Container for string documentation on a command line tool.
     *
     * @signature class ToolDoc;
     *
     * @section Remarks
     *
     * This class is generally not used directly by the user but through @link
     * ArgumentParser @endlink. It allows to store and represent all information
     * related to a command line tool that would normally go into a man page. It can
     * be printed to STL streams in different formats, currently plain text, HTML
     * and man pages are supported.
     *
     * You can also use basic formatting in text. This formatting is tailored to the
     * usage on the command line. Use <tt>\fB</tt> to start bold font, <tt>\fI</tt>
     * to start italic font and <tt>\fP</tt> to use the previous font (of course,
     * use correct escaping of the backslash in C strings, so use <tt>"\\fB"</tt>,
     * <tt>"\\fI"</tt>, and <tt>"\\fP"</tt> in your code.
     *
     * @section Examples
     *
     * The following shows a brief example of how to use @link ToolDoc @endlink.
     *
     * @code{.cpp}
     * ToolDoc doc;
     * setName(doc, "RazerS");
     * setShortDescription(doc, "Read mapping with controllable sensitivity.");
     * setDate(doc, "04 March 2012");
     * setVersion(doc, "1.0");
     * setCategory(doc, "Read Mapping");
     * setManTitle(doc, "SeqAn Apps Reference Manual");
     *
     * addSection(doc, "Synopsis");
     * addText(doc, "\\fBrazers\\fP [\\fIOPTIONS\\fP] \\fIREFERENCE\\fP \\fIREADS\\fP", false);
     * addText(doc,
     *         "\\fBrazers\\fP [\\fIOPTIONS\\fP] \\fIREFERENCE\\fP \\fILEFT_READS\\fP "
     *         "\\fIRIGHT_READS\\fP", false);
     *
     * addSection(doc, "Description");
     * addText(doc,
     *         "RazerS is a read mapper with controllable, sensitivity.  This "
     *         "means that you can find all read matches in the reference sequence "
     *         "and optionally, you can trade lower sensitivity for better "
     *         "performance.");
     * addText(doc,
     *         "What's special about RazerS is that you can control the sensitivity.");
     *
     * addSection(doc, "Options");
     * addSubSection(doc, "Main Options");
     * addListItem(doc, "\\fB-id\\fP, \\fB--indels\\fP",
     *             "Enable mapping with indels enabled.");
     * addListItem(doc, "\\fB-i\\fP, \\fB--identity\\fP \\fIIDENTITY\\fP",
     *             "Set minimal identity of matches to find.");
     *
     * print(std::cout, doc, "text");
     * @endcode
     *
     *
     * @see ToolDoc#addText
     * @see ToolDoc#addListItem
     * @see ArgumentParser
     *
     * @fn ToolDoc::ToolDoc
     *
     * @brief Constructor
     *
     * @signature ToolDoc::ToolDoc()
     *
     * @fn ToolDoc#append
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Append two @link ToolDoc @endlink objects.
     *
     * @signature void append(a, b);
     *
     * @param[in,out] a This object is updated
     * @param[in] b This object is appended to <tt>b</tt>.
     *
     * @fn ToolDoc#setName
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Set the tool name.
     *
     * @signature void setName(toolDoc, name);
     *
     * @param[in,out] toolDoc The ToolDoc object to the set the name for.
     * @param[in] name The name of the tool (@link CharString @endlink).
     *
     * @fn ToolDoc#getName
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Get the tool name.
     *
     * @signature CharString getName(toolDoc);
     *
     * @param[in] toolDoc The ToolDoc object to the get the name for.
     *
     * @return CharString Resulting name (@link CharString @endlink).
     *
     * @fn ToolDoc#setCategory
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Set the tool name.
     *
     * @signature void setName(toolDoc, name);
     *
     * @param[in,out] toolDoc The ToolDoc object to the set the name for.
     * @param[in] name The name of the tool (@link CharString @endlink).
     *
     * @fn ToolDoc#getCategory
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Get the tool category.
     *
     * @signature CharString getCategory(toolDoc);
     *
     * @param[in] toolDoc The ToolDoc object to the get the category for.
     *
     * @return CharString Resulting category (@link CharString @endlink).
     *
     * @fn ToolDoc#setShortDescription
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Set the tool short description.
     *
     * @signature void setShortDescription(toolDoc, text);
     *
     * @param[in,out] toolDoc The ToolDoc object to the set the short description
     *                        for.
     * @param[in] text The short description of the tool (@link CharString
     *                 @endlink).
     *
     * @fn ToolDoc#getShortDescription
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Get the tool short description.
     *
     * @signature CharString getShortDescription(toolDoc);
     *
     * @param[in] toolDoc The ToolDoc object to the get the short description for.
     *
     * @return CharString Resulting short description (@link CharString @endlink).
     *
     * @fn ToolDoc#setDate
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Set the date string.
     *
     * @signature void setName(toolDoc, str);
     *
     * @param[in,out] toolDoc The ToolDoc object to the set the date string for.
     * @param[in] str The date string of the tool (@link CharString @endlink).
     *
     * @fn ToolDoc#getDate
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Get the date.
     *
     * @signature CharString getDate(toolDoc);
     *
     * @param[in] toolDoc The ToolDoc object to the get the date from.
     *
     * @return CharString Resulting date string (@link CharString @endlink).
     *
     * @fn ToolDoc#setVersion
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Set the tool version string.
     *
     * @signature void setName(toolDoc, str);
     *
     * @param[in,out] toolDoc The ToolDoc object to the set the version string for.
     * @param[in] str The version string of the tool (@link CharString @endlink).
     *
     * @fn ToolDoc#getVersion
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Get the tool version string.
     *
     * @signature CharString getVersion(toolDoc);
     *
     * @param[in] toolDoc The ToolDoc object to the get the version string.
     *
     * @return CharString Resulting version string (@link CharString @endlink).
     *
     * @fn ToolDoc#setManTitle
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Set the man title.
     *
     * @signature void setTitle(toolDoc, title);
     *
     * @param[in,out] toolDoc The ToolDoc object to the set the title for.
     * @param[in] title The title of the tool (@link CharString @endlink).
     *
     * @fn ToolDoc#getManTitle
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Get the tool man page title of.
     *
     * @signature CharString getManTitle(toolDoc);
     *
     * @param[in] toolDoc The ToolDoc object to the get the man page title.
     *
     * @return CharString Resulting man page title (@link CharString @endlink).
     *
     * @fn ToolDoc#addSection
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Add a section with the given title.
     *
     * @signature void addSection(toolDoc, title);
     *
     * @param[in,out] toolDoc The ToolDoc object to add a section for.
     * @param[in] title The section title (@link CharString @endlink).
     *
     * @fn ToolDoc#addSubSection
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Add a subsection with the given title.
     *
     * @signature void addSubSection(toolDoc, title);
     *
     * @param[in,out] toolDoc The ToolDoc object to add a subsection for.
     * @param[in] title The subsection title (@link CharString @endlink).
     *
     * @fn ToolDoc#addText
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Add a text line/paragraph to ToolDoc.
     *
     * @signature void addText(toolDoc, text[, isParagraph]);
     *
     * @param[in,out] toolDoc The ToolDoc to add the text to.
     * @param[in] text The text to add (@link CharString @endlink).
     * @param[in] isParagraph Whether to insert as paragraph or just a line (only
     *                        one line break if not a paragraph).
     *
     * @fn ToolDoc#addListItem
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Add a list item to a ToolDoc.
     *
     * @signature void addListItem(toolDoc, key, value);
     *
     * @param[in,out] toolDoc The ToolDoc object to add the list item to.
     * @param[in] key The key for the list (@link CharString @endlink).
     * @param[in] value The value for the list (@link CharString @endlink).
     *
     * @fn ToolDoc#print
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Print ToolDoc object in a given format.
     *
     * @signature void print(stream, toolDoc, format);
     *
     * @param[in,out] stream The <tt>std::ostream</tt> to write to.
     * @param[in] toolDoc The ToolDoc to print.
     * @param[in] format The format, one of {"html", "man", "txt"}.
     *
     * @fn ToolDoc#clearEntries
     *
     * @headerfile <seqan/arg_parse.h>
     *
     * @brief Clear entries from ToolDoc.
     *
     * @signature void clearEntries(toolDoc);
     *
     * @param[in,out] toolDoc The ToolDoc object to clear entries from.
     */