IBM Streams 4.2

Documenting your SPL toolkits

You can use SPLDOC markup and the spl-make-doc command to generate rich text documentation for your SPL toolkits.

You can use SPLDOC markup in the SPL file code comments and model file descriptions associated with the SPL artifacts in a toolkit. Then, you can run the spl-make-doc command to generate HTML documentation and images that can be viewed in a browser. This command generates documentation by interpreting the SPLDOC markup in the SPL code and model files in a toolkit.

You can use the spl-make-doc command to generate documentation for either a single or multiple toolkits. Include generated documentation for the toolkit in the doc subdirectory of the toolkit.

You can mark up and generate documentation for the following SPL artifacts in a toolkit:

SPL files and their components. SPL files end in the .spl extension and SPL mixed mode files end in the .splmm extension.
Namespaces. A namespace is described in a file that is named namespace-info.spl in the namespace directory of a toolkit.
Primitive operators and native functions. These artifacts are described in operator and function model files.
Toolkits. A toolkit is described in an info.xml file.

To prepare the documentation for the toolkit artifacts, you can add SPLDOC markup to your toolkit.

Associate SPLDOC comments with each SPL file, composite operator, SPL function, and global or static SPL type.
Add the namespace description as a comment in the namespace-info.spl file.
For primitive operators and functions, use SPLDOC markup in the description elements of the XML model files.
Add overview information for the toolkit to the description element of the toolkit information model file (info.xml) for the toolkit.

Note: Although descriptions are desirable, they are not required. The spl-make-doc command generates documentation that describes the contents and interfaces of a toolkit even when descriptions are not added to the files.

For examples of toolkit documentation, refer to the toolkits shipped with the product, and to the generated documentation in SPL standard and specialized toolkits.

To provide appropriate documentation for the following artifacts, describe the functionality, expected inputs, and generated outputs and make sure the following information is included.

Primitive operators

Include these items:

For each input or output port, state whether it needs a specific stream type, or a particular attribute name and type.
For each parameter, list accepted data types and value ranges, and, if any, default values.
For each input port that allows windowing configurations, indicate the conditions in which window punctuation is generated.
Describe the conditions in which an operator might throw an exception (for example, an operator cannot open a file). Exceptions can be documented by using the @throws SPLDOC annotation tag.
Include an example of an operator invocation by using <codeTemplates> and <codeTemplate> tags in the operator model.

Composite operators

Include these items:

For each input or output port, state whether it needs a specific stream type, or a particular attribute name and type.
For each parameter, list accepted data types and value ranges, and, if any, default values.
Describe any configuration constraints that the composite operator has that can interact with the application configuration, such as partition and host placement constraints.
Include an example of using the composite operator. Choose an example that is a complete SPL program that can be compiled and run by a third party. For structural composite operators, include a figure of the composite operator expansion that results from the composite operator use.

Toolkits

Include these items:

Summary of changes: Provide a list of updates to the toolkit from a previous version (if any). As a best practice, the toolkit starts with version number 1.0.0 and incrementally changes version numbers according to a VRM (Version, Release, and Modification) format. Toolkit versions are specified in the Toolkit information model (info.xml).
Overview: Provide an overview of the toolkit and its artifacts.
Installation instructions: Provide precise instructions on how to download and install the toolkit, and any dependencies that are required by the toolkit implementation (such as libraries).
Helper artifacts: Document the function and usage of auxiliary tools (such as scripts) that are included in the toolkit.
Example usage: Create an example of an application that uses operators, composite operators, functions, and stream types in the toolkit. Choose an example that is a complete SPL program that can be compiled and run by a third party. Place the source files for the example in a separate sample toolkit. To document the sample, use the @sample SPLDOC annotation tag in the toolkit description in the toolkit information model file (info.xml) of the sample toolkit and add descriptions for the sample toolkit artifacts. Use SPLDOC link markup to add cross references between the main and sample toolkits.