Comments

This information describes the comment syntax for the SPL artifacts in SPL files. SPLDOC comments are delimited by the forward slash and asterisk characters.
The following examples show how to format SPLDOC comments in an SPL file. In the XML model files for primitive operators, native functions, and the toolkit manifest (info.xml), the SPLDOC markup text is added to the description elements of the model file.
/**comment text*/
Comment text is specifically preceded by the asterisk decorator
This example uses the asterisk decorator immediately before the comment text even though it is not required. The asterisk decorator consists of two characters: one space and the asterisk. This use of the asterisk decorator helps to make your code neater. Including this decorator also makes it easier to encode lists.
/**
 * This is a valid SPLDOC comment.
 */
Comment text is not specifically preceded by the asterisk decorator
The asterisk decorator is not required at the beginning of the comment line. This example shows a valid comment without the asterisk decorator before the comment text.
/**
This is also a valid SPLDOC comment.
 */
White space that precedes the asterisk decorator is trimmed
Any white space that precedes the asterisk decorator is trimmed. As a result, the following example comments are valid and generate the same documentation.
/**
 * This is a valid SPLDOC comment.
 */
/**
        * This is also a valid SPLDOC comment.
 */
Note: On subsequent lines, any characters that are in, or beyond, the same column as the start of the first line of text are treated as SPLDOC markup, and are not trimmed. This behavior can affect code blocks and lists.
Incorrect format for the decorator
The decorator consists of two characters: an asterisk that is followed by a space. When the asterisk is not followed by a space, the asterisk is interpreted as plain text in the generated documentation. All the lines of an SPLDOC comment must either use an asterisk decorator, or not use it. The SPLDOC comment is not correctly formatted when only some of the comment lines use the asterisk decorator. The following markup treats the asterisk as plain text:
/**
 *This is not a valid SPLDOC comment.
 */
Because the asterisk is not followed by a white space just before the comment text, the following plain text is generated:

*This is a not a valid SPLDOC comment.

Artifacts that support SPLDOC comments

You can add SPLDOC comments to the following artifacts. Comments that are associated with entities other than the following artifacts are not processed by the spl-make-doc command. For example, comments that are embedded in the graph of a composite operator or comments that are not placed directly above an SPL artifact are not processed.
SPL files
Place comments at the top of a file. Add at least one blank line between the end of the comment and the namespace statement, if that statement exists in the file.
Note: If the blank line that precedes the namespace statement is omitted, the comment is not included in the generated output.
Namespaces

To generate documentation for a namespace, you can create an SPL file that is called namespace-info.spl within the appropriate namespace directory in the toolkit. Place the comment at the top of the file. Add at least one blank line between the end of the comment and the namespace statement, if that statement exists in the file, and do not include any artifact definitions in the file.

Note: If the blank line that precedes the namespace statement is omitted, the comment is not included in the generated output.
/**
* Description of the namespace.
*/

namespace com.teracloud.streams.db;
Standalone types
Place the comment directly above the type definition. Do not add a blank line.
Composite operators
Place the comment directly above the head of the composite operator. Do not add a blank line.
Composite operator types
Place the comment directly above the operator type of the composite operator. Do not add a blank line.
Functions
Place the comment directly above the head of the function. Do not add a blank line.
Function models, operator models, info.xml file
Place SPLDOC comments in the description element. The XML reserved characters in the comment text must be encoded by using HTML entity encoding. For example, use &lt; and &gt; for < and > symbols in the description element.