Documenting custom functions

You can add descriptions and examples to your custom functions in the form of documentation comments. In a user interface (UI), this documentation appears when someone hovers over or clicks on the custom function.

Documentation comments versus regular comments

Documentation comments differ from regular comments. Use documentation comments to explain how to use a custom function and regular comments to explain what a custom function does:

• Documentation comments provide documentation that appears in a UI to help users understand how to use a custom function.
• Regular comments help admins and power users understand what the pieces of a custom function do.

Documentation comment tagging

You use a special type of comment tag to document custom functions:

1. The documentation comment starts with the /** tag.
2. After the first line, each line of the documentation comment must begin with an asterisk * .
3. Use the backtick ( ` ) character to format text in the monospace font. Monospace font is typically used on command, function, dataset, parameter, and field names to distinguish these names from the surrounding text.
4. The documentation comment ends with the */ tag.

You place the documentation comment immediately before the function definition.

Specifying function and parameter descriptions

Consider this custom function called isError:

function isError($code : number) : boolean {
  return $code >= 400 
}

You can specify an overall description for a custom function and descriptions for each parameter that is defined in that custom function. If the descriptions appear in a Ui, keep the descriptions short and concise.

Overall description

The overall description must be at the beginning of the documentation comment. Make the overall description one or more sentences in length.

Parameter descriptions

The parameter descriptions must begin with @param followed by the name of the parameter. For example, @param $field.

Description and parameter example

Here is an example of the overall description and parameter descriptions inside a documentation comment for the isError custom function:

/**
 * Looks for error codes greater than or equal to 400 and returns a Boolean value. 
 *
 * @param $code - A numeric field that contains http error codes.
 */
function isError($code : number) : boolean {
  return $code >= 400 
}

Notice that the document comment appears immediately before the definition for the isError custom function.

Including examples in a documentation comment

You can include examples in the documentation comment for a custom function.

Format an example

Examples in a documentation comment must be formatted in a specific way:

1. Each example must begin with @example.
2. You can include a description of the example.
3. To format the SPL2 in the example:
   1. Start the SPL2 with three backtick ( ``` ) characters and the word spl.
   2. End the example with three backtick ( ``` ) characters.
   3. Insert a blank line between each example for readability in a UI.

Here is an example:

 * Looks for error codes greater than or equal to 400 and returns a Boolean value. 
 *
 * @param $code - A numeric field that contains HTTP error codes.
 *
 * @example 
 * This example invokes the `isError` function in the `where` command to filter 
 * the data in the `jsondata` index. The `status_code` field is the value used for 
 * the `$code` parameter.
 * ```spl
 * search index=jsondata | where method="GET" AND isError(status_code)
 * ```

Documentation comment examples

The following example includes a documentation comment that contains an overall description, parameter descriptions, and multiple examples:

/**
 * The `top` function processes the events in a dataset and returns the top-most 
 * values in a specific field. 
 *
 * @param $source - Identifies the dataset that the command operates on.
 * @param $field - The field name. Used in the `stats` command part of the function. 
 * The `stats` command counts the events and organizes the count by the 
 * values in the `$field`.
 * @param $limit - Specifies the maximum number of results to return. 
 * The value specified for `$limit` must be an integer. 
 * The `head` command returns the top values in the results from the `sort` 
 * command, up to the maximum number allowed by the `$limit` parameter.
 *
 * @example 
 * Return the top 5 values from the `host` field.
 * ```spl
 * from sample_data_index | top host 5
 * ```
 * 
 * @example
 * Return the top 12 values from the `clientip` field.
 * ```spl
 * FROM main | top clientip 12
 * ```
 */
function top($source, $field, $limit: int) {
    return | FROM $source 
        | stats count() by $field 
        | sort -count
        | head $limit
}

In addition to adding a documentation comment to a function, you can add regular comments as well. The following example is the same as the previous example, with the addition of regular comments to describe parts of the function.

/**
 * The `top` function processes the events in a dataset and returns the top-most 
 * values in a specific field. 
 *
 * @param $source - Identifies the dataset that the command operates on.
 * @param $field - The field name. Used in the `stats` command part of the function. 
 * The `stats` command counts the events and organizes the count by the 
 * values in the `$field`.
 * @param $limit - Specifies the maximum number of results to return. 
 * The value specified for `$limit` must be an integer. 
 * The `head` command returns the top values in the results from the `sort` 
 * command, up to the maximum number allowed by the `$limit` parameter.
 *
 * @example 
 * Return the top 5 values from the `host` field.
 * ```spl
 * from sample_data_index | top host 5
 * ```
 * 
 * @example
 * Return the top 12 values from the `clientip` field.
 * ```spl
 * FROM main | top clientip 12
 * ```
 */
function top($source, $field, $limit: int) {
    return | FROM $source 
        | stats count() by $field // COUNTS THE EVENTS, ORGANIZED BY $FIELD
        | sort -count // SORTS THE COUNTS IN DESCENDING ORDER
        | head $limit // RETURNS THE EVENTS, UP TO THE $LIMIT NUMBER
}

See also

Functions

Custom eval functions

Custom command functions

Related information

Using comments in SPL2 in the SPL2 Search Manual