Formatting conventions

By following the formatting conventions when you mark up the toolkit artifacts, you ensure that the spl-make-doc command interprets the markup correctly and generates the expected results.

First sentence in a comment block or new page is used as a summary

The first sentence in a comment block is used as a summary description of the associated SPL artifact, and the first sentence of a new page is used as the summary description of the page. In the following example of an SPLDOC comment for a composite operator, this sentence is used to summarize the entry for the composite operator in the document that is generated for the namespace: Outputs a stream of hello world greeting messages. 
/**
 * Outputs a stream of **hello world** greeting
 * messages. Each message in the stream contains
 * a string with the **hello world** message.
 */

Inline markup can span multiple lines

In the following SPLDOC comment, the italicized text spans two comment lines. The comment lines are concatenated into a single line in the generated HTML.

/**
This is *very 
important*.
*/
This is <em>very important</em>.

Inline markup cannot span paragraphs

When inline markup spans multiple paragraphs, the markup characters are treated as plain text. In the following SPLDOC example, the opening and closing markup for bold ( ** ) spans paragraphs and is not interpreted:

/**
This is **very 

important**.
*/
The spl-make-doc command generates HTML similar to this code.
<p>This is **very
</p>

<p>important**.
</p>

Inline markup must be next to the enclosed text

When white space separates the inline markup tags from the enclosed text, the text is interpreted as plain text in the HTML output. In the following example, the markup tag for bold ( ** ) at the end of the sentence is preceded by a space. As a result, the SPLDOC markup for bold is treated as plain text.

This is **very important **.

The spl-make-doc command generates HTML similar to this code.

<p>This is **very important **.
</p>