Generating documentation for your EPL code

Code constructs that are documented

The ApamaDoc generates documentation for the following code constructs:

• Monitors
• Events (defined outside monitors)
• Fields, constants and actions on events
• Custom aggregate functions
• Fields, constants and actions on custom aggregate functions
• Plug-in import statements

By default, the ApamaDoc export wizard does not generate documentation for inner fields or events of a monitor. If you want to include inner fields and events of a monitor, generate ApamaDoc without a user interface using the --includeMonitorMembers option. See Generating ApamaDoc from the command line or Generating ApamaDoc from an Ant script for more information.

To find out how ApamaDoc can be useful for documenting the storage and flow of personal data within your application, see Documenting personal data flows within an Apama application.

Steps for using ApamaDoc

The general steps for using ApamaDoc are as follows:

1. Create an Apama project in Apama Plugin for Eclipse.

2. Add a .mon file to your project.

3. In the .mon file, enhance the automatically generated documentation by adding annotations. See Inserting ApamaDoc comments, Inserting ApamaDoc tags, and Inserting ApamaDoc references.

4. Save and build the project.

5. Right-click the project name and select Export from the context menu.

6. In the Export dialog, expand Apama, select ApamaDoc Export, and click Next.

7. Identify the folder that you want to contain the ApamaDoc output, and click Finish.

To view the ApamaDoc output, go to the output folder you identified and double-click the index.html file. The generated ApamaDoc opens in your browser.

Try this with any project you already have. Even if you have not added any ApamaDoc annotations, you can see that ApamaDoc automatically generates a lot of documentation.

Inserting ApamaDoc comments

To augment the documentation automatically generated by ApamaDoc, insert comments in your EPL files in the following format:

1. Start the comment with the /** characters, rather than the usual /* notation.

2. Enter the text you want to appear in the generated documentation.

3. After each newline, to continue the ApamaDoc comment, insert a * character at the beginning of the next line.

4. As needed, insert one or more tags for particular constructs. See Inserting ApamaDoc tags. Any tags must occur at the beginning of a newline (ignoring * and whitespace characters). Documentation for a tag ends when you declare another tag or end the comment.

5. End the comment with the usual */characters.

For example, your EPL code might look like this:

/**
 * Called by the monitor when it executes the onload() action.
 * This action maintains the configuration for this scenario.
 * @param sId The scenario ID.
 * @param updateCallback The callback after the configuration is updated.
 */
action init(string sId, action<> updateCallback) {
    scenarioId:=sId;
    route GetConfiguration(scenarioId);
    listener l:=on Configuration(scenarioId=scenarioId) as c {
        config := c.configuration;
        defaultConfig := c.defaults;
        configurationUpdated();
        updateCallback();
    }
    listeners.append(l);
}

When ApamaDoc processes these comments, it removes initial and trailing whitespace and * characters. For example, the ApamaDoc output would look like this:

init

void init(string sId, action< > updateCallback)

Called by the monitor during execution of the onload() action. This action
maintains the configuration for this scenario.

Parameters:

   sId - The scenario ID.
   updateCallback - The callback after the configuration is updated.

Listens:

com.apama.scenario.Configuration

Inserting ApamaDoc tags

ApamaDoc automatically generates documentation for EPL code constructs. To enhance the quality of the documentation, you can insert tags that let you provide and link to additional information. A tag begins with an @ symbol and is immediately followed by a name and other information. The following table describes the tags you can insert.

Inserting ApamaDoc references

Many ApamaDoc tags contain links to other parts of the EPL code. These tags specify one of the following link types:

• Code references
• Type references
• Event references
• Action references

A code reference is a link to a monitor definition, an event type definition, an action definition, a member (variable or named constant) declaration or an import declaration. A code reference has two forms.

The first form links to constructs that are in the monitor definition or event type definition that contains this ApamaDoc comment. The target of the link can be a variable declaration, named constant declaration, import declaration, or action definition. The format for this code reference is as follows:

[ # ](member | import | ( action() ) )

The hash symbol is optional. You must specify one of the following:

• Name of a member (variable or named constant) that is in the monitor or event type definition that contains this ApamaDoc comment.

• Name of an item that is being imported in the monitor or event type definition that contains this ApamaDoc comment.

• Name of an action that is in the monitor that contains this ApamaDoc comment. If you specify an action, the name of the action must end with parentheses. For example:

  #updateOrder()
  

The second form links to constructs that are not in the monitor or event type definition that contains this ApamaDoc comment. You can link to code constructs that are in the same package or in other packages. The format for this code reference is as follows:

[ package [. monitor ].]type[ #(member | import | ( action() ) )]

Replace type with the name of a monitor or event type definition. If the ApamaDoc comment is in the same package as the link target, the package specification is optional. If you replaced type with the name of an event that is defined in a monitor, you must replace monitor with the name of that monitor and you must specify the package name.

The hash symbol followed by a name is required when the link target is a variable declaration, named constant declaration, import declaration, or action definition. If you specify an action, the name of the action must end with parentheses.

If the code reference is valid the rendered HTML output contains a hyperlink to the referenced code construct’s documentation followed by the descriptions text, if any. If the reference is not valid, the output displays only the tag’s description text if you provided it.

A type reference is a subset of a code reference. It always links to a monitor or event type definition.

An event reference is a subset of a type reference. It always links to an event type definition.

An action reference is a subset of code reference. It always links to an action. The action can be in an event type definition, in a monitor, or in an event type definition that is in a monitor.

Inserting EPL source code examples

ApamaDoc supports the <code>...</code> tag in ApamaDoc comments. You can use this tag to specify code snippets as part of the comment. In this case, you need not specify the comment character (*) at the beginning of each line.

The ApamaDoc <code> tag is a block element, and is not the same as the HTML <code> tag that is used for inline markup. Unlike the HTML <code> tag, the ApamaDoc <code> tag preserves the indentation and line breaks of the code snippet. You need not use the HTML <br> tag to force a line break.

If you want to mark up pieces of program code within the running text, use the HTML tag <tt>.

In many cases, you can enter the less-than (<) and greater-than (>) signs as they are. However, you need to take care when you have text that is enclosed in these signs in your comment and which has no spaces between the text and these signs (for example, sequence<string>). This will be interpreted as an HTML tag. To avoid this, we recommend that you always add spaces (for example, sequence< string >). If this is not possible for your particular use case, you have to use the < and > entities instead (for example, sequence<string>). So check the generated result carefully if you are using these signs.

Example:

/**
 * This is an example of a comment.
 *
 * When using the <tt>code</tt> tag, all indentation and line breaks
 * are preserved.
<code>
sequence< string > s :=
   ["Something", "Completely", "Different"];
print ", ".join(s);
</code>
 * Note that the above < and > signs will be generated unchanged
 * because spaces have been added.
 */

Generating ApamaDoc from the command line

The apamadoc tool generates HTML documentation in ApamaDoc format from EPL files (.mon files).

The executable for this tool is located in the bin directory of the Apama installation. Running the tool in the Apama Command Prompt or using the apama_env wrapper (see Setting up the environment using the Apama Command Prompt) ensures that the environment variables are set correctly.

Synopsis

To generate HTML documentation from EPL files using the apamadoc tool, run the following command:

apamadoc [*options*] *output_folder* *input*...

When you run this command with the --help option, the usage message for this command is shown.

Description

The apamadoc tool generates the HTML documentation in the specified output folder, using the input method described below.

You can automatically link to an external ApamaDoc documentation. If you are online and have access to the official Apama documentation, if a type is not available in your ApamaDoc, but can be found in the official API Reference for EPL (ApamaDoc), the apamadoc tool automatically adds a link to the official ApamaDoc. If this is not possible, the type remains unlinked.

You can view the ApamaDoc by opening output_folder/index.html in a web browser.

Options

The apamadoc tool takes the following options:

Operands

The apamadoc tool takes the following operands:

Examples

The following examples show the different ways in which the apamadoc tool can be started:

• Generate documentation in the doc folder, using the EPL files listed in the epl_list.txt file:

  apamadoc doc @epl_list.txt
  

• Generate documentation as above, but with “Example” as the title in the generated documentation:

  apamadoc -t "Example" doc @epl_list.txt
  

• Generate documentation in the doc folder, recursively processing the EPL files in the src/epl folder with verbose output enabled:

  apamadoc -v doc src/epl
  

• Generate documentation in the doc folder from the src/epl/example.mon file only:

  apamadoc doc src/epl/example.mon
  

• Generate documentation in the doc folder, using the following: the EPL files listed in the epl_list.txt file, the EPL files recursively found in the src/epl folder, and the myepl.mon file from the parent folder:

  apamadoc doc @epl_list.txt src/epl../myepl.mon
  

Generating ApamaDoc from an Ant script

Generating ApamaDoc from an Ant script is useful if you want to control what ApamaDoc generates without user-interface intervention, for example, when you are running nightly build integrations. Also, using the Ant script, you can control which files are exported and which files are omitted. See the generate-apamadoc macro definition in the apama-macros.xml Ant script for more details. You can find this Ant script in the etc directory of your Apama installation.

To generate ApamaDoc from an Ant script, you have to create a build.xml Ant script that uses the generate-apamadoc macro to build ApamaDoc for the EPL files you wish to document. For example:

<?xml version="1.0" encoding="UTF-8"?>
<project name="" default="apamadoc" basedir=".">
  <property environment="env"/>
  <import file="${env.APAMA_HOME}/etc/apama-macros.xml"/>
  <target name="apamadoc">
    <generate-apamadoc outputDir="./apamadoc-output" title="ApamaDoc Title">
      <!-- standard Ant fileset to specify which files should be documented -->
      <fileset dir="./monitors">
         <include name="**/*.mon"/>
      </fileset>
    </generate-apamadoc>
  </target>
</project>

By default, ApamaDoc is only generated for the API exposed by the specified EPL files. The members of monitors are therefore not generated (for example, inner events, variables and constants, fields in events, and actions). This can be enabled, however, using the includeMonitorMembers attribute.