Lesson 3: Checking for Documentation

This rule will report a violation when methods with more than 17 statements do not have documentation.

Designing the Rule Pattern

Creating the Parent Node

To start composing this rule, open Declarations, right-click the Method node, then choose Create Rule from the shortcut menu.

You should see the following parent rule node in the right pane of the GUI:

We now have the basic building block for a rule about methods.

Adding Further Qualifications to the Parent Rule Node

To specify that we want this rule to check only declared methods and not references to methods, first add the IsDecl property by right-clicking the Method rule node (in the workspace panel) and choosing IsDecl from the shortcut menu that opens.

To have Jtest check the statements in the body of the method, right-click the Method node and choose Body.

Right-clickthe Body node and choose Modify. Choose the Statements node from the list of items in the Modify Node window that appears, then click OK.

Right-click the Body rule node again, then choose Create Collector from the shortcut menu. A collector symbol (pentagon) will appear below the Body node.

Right-click on the collector and choose Count #. To modify the value of Count, right-click he Count box and choose Modify. In the Modify Expression dialog window that opens, enter $$>17 in the Expression field.

Right-click the Method node and choose HasJavadoc from the list. Then right-click HasJavadoc and choose Toggle from the shortcut menu that appears. In our example, we want the method to be flagged if it does not have any Java documentation, so we need to set HasJavadoc to false (F).

Specifying an Error Message

Finally, we need to specify what text Jtest should print when this rule is violated. The first step in doing this is right-clicking the parent rule node (here, the Method rule node), then choosing Create Output from the shortcut menu. This action will invoke the following Customize Output window.

In the Customize Output window, enter the message that you want Jtest to deliver when this rule is violated. In this example, you might enter, "Missing Javadoc comment for: $name". When this message is reported by Jtest, $name will be replaced by the actual name of the method.

Click OK.

Your rule should now look like this:

Your rule now tells Jtest to report the specified error message when a method with more than 17 lines does not contain documentation. Your rule is now complete. After you customize this rule's properties and save it, Jtest will be able to enforce it.

Customizing Rule Properties

Rule properties can be customized via the Rule Properties panel. To access this panel, choose Rule> Properties.

You will then see the Rule Properties panel.

This panel lets you determine the rule's properties. In the CodeWizard tab, enter...

• a rule ID: the unique ID you want to assign to this rule. If you want Jtest to organize your custom rules into categories, use the following format:

  category.id

  For example, you could use "Example.JAVADOC"

• a header: the name you want Jtest to assign to this rule. For this example, you could enter

  All methods with statements greater than 17 need java documentation

Next, choose the rule's severity. This rule should be categorized as a Violation.

Finally, click the Info tab, and enter the name of the rule's author (your name and/or development group) and a description of the rule. (This description will be displayed when users choose View Rule Description within Jtest).

When you have entered all of these values, click OK to close this panel.

For more information on any of the fields in the Rule Properties panel, see the section Rule Properties Panel.

Saving and Enabling Your Rule

Before you begin composing another rule, or before you exit the program, you will want to save your rule (Jtest only enforces rules that have been saved).

To save your rule, choose Rule> Save or Rule> Save As. This command will invoke a file chooser in which you can specify the rule's filename and path. Be sure to give each rule you save a .rule extension. If you do not use this exact extension, Jtest will not load your rules properly. Also, be sure to save your rules within the default directory (<Jtest installation directory>/jrules). If a rule is not contained in this directory, Jtest will not enforce it.

After you save your rule, exit RuleWizard. To enable your rule:

1. Click Global in either of Jtest's UIs.
2. In the Global Test Parameters window, go to Static Analysis> Rules> User Defined Rules, then right-click User Defined Rules. A shortcut menu will open.
3. Choose Reload Rules from the shortcut menu that opens.

Your rule will then be enabled.

Enforcing Your Rule Automatically

If you look at the Global Test Parameters tree's Static Analysis> Rules> User Defined Rules branch, you will see that Jtest automatically added and enabled the rule you just created.

This rule will now be included in the set of rules Jtest applies to your class or classes during static analysis.