Labels, identifies, and provides comments regarding various CCL components.
CCL modules can include documentation tags that label, identify, and provide comments regarding various CCL components. A few of these tags are interpreted by Sybase CEP Studio, which displays the text provided by the tags in combination with the associated components. You can use CCL documentation to help organize and structure your comments.
The following characteristics apply to all documentation tags, except where noted otherwise.
Documentation tags are entered within query module .ccl files, and are set off by special characters similar to comments.
Documentation tags appear in tag blocks. A tag block is a continuous group of lines marked with documentation tag characters.
Any of the following methods can be used to designate tag blocks:
|
Beginning of Tag Block |
End of Tag Block |
|
|---|---|---|
|
Method 1: |
Three hyphens (---) on a new line. |
New line, which is not immediately followed by another documentation tag line. |
|
Method 2: |
Three slashes (///) on a new line. |
New line, which is not immediately followed by another documentation tag line. |
|
Method 3: |
Two hyphens and an exclamation point (--!) on a new line. |
New line, which is not immediately followed by another documentation tag line. |
|
Method 4: |
Two slashes and an exclamation point (//!) on a new line. |
New line, which is not immediately followed by another documentation tag line. |
|
Method 5: |
A slash and two asterisks (/**). |
An asterisk and slash (*/). |
Note that leading spaces are ignored for methods 1 through 4. When the tag lines are processed:
Their markings are stripped, along with any white spaces surrounding them.
Any multiple blank lines within the tag block are stripped to one blank line and multiple blank spaces are stripped to one space. If the resulting tag block contains one or more blank lines, the fragments of text separated by the blank lines are interpreted as separate paragraphs. It is possible to use this feature to create multi-paragraph documentation tags. For example, the first paragraph could be used as a summary and a second paragraph to provide a more detailed description. However, note that second and subsequent paragraphs are not displayed in the Sybase CEP Studio Explorer View.
If Method 5 is used to designate documentation tag lines, any additional asterisks, appearing in a sequence with the asterisks that mark the beginning or end of the tag block are stripped.
If Method 5 is used to designate documentation tag lines, any leading asterisks at the beginning of the second or subsequent lines of the tag block are also stripped.
The tag marker in methods 1-4, or the opening tag marker in method 5, is followed by one or more valid documentation tags. Tags are made up of the following components:
All tags begin with an initial "at" sign (@) (the "at" sign must appear as the first character after the tag marker, not counting white space, to be interpreted as the beginning of a tag; all other "at" signs within the tag markers are treated as literal text), followed immediately by a valid tag name with no intervening space.
Some tags require that the tag name be followed by an identifier, consisting of one or more non-space characters, which identify the module or CCL statement component being tagged.
Most (but not all) tag types accept one or more lines of tag text.
Documentation tags can be applied to modules or to some, or all types of CCL statements, depending on the tag type.
Tags that apply to statements must appear before the statements to which they apply with no other intervening statements.
No tags can appear after the last statement in the module.
Tags that apply to the module must appear inside the same tag block.
No statement can have more than one associated tag with the same tag type and identifier.