Namespace Scope of Entities and the @scope Tag

The visibility of a function or variable and how to describe it are vital concepts to understand when using the Dashboard Architect documentation system.

In JavaScript, variables (including variables that are pointers to functions) may be visible in various scopes. In the context of JavaScript within Interactive Reporting Studio, the default scope for a variable is to be visible within the current event handler, anywhere after it is declared or first used.

It is common practice to expose a variable to other event handlers by attaching the variable to the parent section of the event handler or to the active document.

The @scope tag enables the visibility of a variable to be documented, making it clear in the generated documentation how the variable is accessed or how the function is called. Previous examples have illustrated one use of the @scope tag in associating functions and variables with classes.

For example, if a variable is defined and used in an event handler and not exposed, no other event handler can use it. If a variable is defined and attached to the parent section object, other event handlers can access that variable through the parent section. If a variable is defined and attached to the active document, other event handlers can access that variable by name because it is visible at the highest level. These examples illustrate different levels of visibility and how to use the @scope tag to document the levels.

/**
 * Returns the result of in_intA * in_intB.
 *
 * If either parameter is not a number, the result is
 * undefined.
 *
 * @param in_intA Integer the number to be multiplied by
 * in_intB
 * @param in_intB Integer the number to be multiplied by
 * in_intA
 * @type Number the result of in_intA * in_intB
 */
function multiply(in_intA, in_intB) {...
}

In the previous example, the function is not visible anywhere other than the current event handler. Because code in other event handlers cannot generally call the function. For this reason, no @scope tag is provided and the documentation system considers this to be a local function and it is not included in the documentation unless control level documentation is requested.

/**
 * Returns the result of in_intA * in_intB.
 *
 * If either parameter is not a number, the result is
 * undefined.
 *
 * @param in_intA Integer the number to be multiplied by
 * in_intB
 * @param in_intB Integer the number to be multiplied by
 * in_intA
 * @type Number the result of in_intA * in_intB
 * @scope Section
 */
function multiply(in_intA, in_intB) {...}
this.Parent.multiply = multiply

The previous example illustrates that the function is exposed through the parent section of the correct shape by the assignment after the closing brace of the function. Because code in other event handlers can easily call the function if they contain a reference to the section. The documentation comment explicitly provides an @scope tag with a scope of Section.

/**
 * Returns the result of in_intA * in_intB.
 *
 * If either parameter is not a number, the result is
 * undefined.
 *
 * @param in_intA Integer the number to be multiplied by
 * in_intB
 * @param in_intB Integer the number to be multiplied by
 * in_intA
 * @type Number the result of in_intA * in_intB
 * @scope Document
 */
function multiply(in_intA, in_intB) {...}
ActiveDocument.multiply = multiply

Finally, the preceding example shows a function that is available to an event handler in the current document by naming the function with no namespace qualifiers. The documentation comment explicitly provides an @scope tag with a scope of Document.

The @scope tag is necessary because JavaScript is type-less, and because the exposure of a function or variable through an assignment need not be done immediately after the function is declared. No reliable method exists for the Dashboard Architect documentation system to determine the visibility of a function or variable from the source code alone.