Escape

The following examples show how you can use the escape character in your SPLDOC markup.

Suppress a markup character

The following example uses the SPLDOC escape markup to suppress the markup character for monospace typeface ( ` ). This example shows a comment in the description field of an XML model file.

    <description>
The \`LinuxPipe\` command to execute. This command can be composed 
of two or more commands chained together using the | piping character 
according to standard piping syntax.
    </description>

Note: If a code block contains a line that starts with the @ character, you must add the SPLDOC escape markup. Otherwise, it is interpreted as an annotation tag.

Output the backslash character

The following example uses the SPLDOC escape markup to output the backslash character.

/**
 * To output a backslash character in single quotation marks, type `\\`.

Note: If a code block contains a line that starts with the backslash character, it is interpreted as an SPLDOC escape markup. You must use two backslash characters to output a single backslash character in this situation. Elsewhere in a code block, escape characters are not required. For example:

/**
    \@: A code block line beginning with "@".
    \\: A code block line beginning with "\".

That SPLDOC markup results in the following output:

@: A code block line beginning with "@".  
\: A code block line beginning with "\".

Avoid unintended, broken links

The following example uses the SPLDOC escape character to keep plain text from creating an unwanted, broken link. The spl-make-doc command interprets square brackets ( [ ] ) as the markup for a link. If you use square brackets to represent an inclusive range in your code comments, the spl-make-doc command creates a link unless you use the escape character with the square brackets. For example, the spl-make-doc command interprets the following range as a link:

[0,...,limit-1]

To treat the range as plain text, use the escape character.

\[0,...,limit-1\] 

Avoid unintended image references that cause errors

The following example uses the SPLDOC escape character to keep plain text from causing a missing image file error. The spl-make-doc command interprets curly brackets ( { } ) as the markup for an embedded image file. If you use curly brackets to represent a set in your code comments, the spl-make-doc command displays an error for a missing image file unless you use the escape character with the curly brackets. For example, the spl-make-doc command interprets the following set as an embedded image and displays an error message:

The `color` parameter is assigned a value from the set {red, blue, green}. 

To treat the curly brackets in the set as plain text, use the escape character.

The `color` parameter is assigned a value from the set \{red, blue, green\}.