doc

The doc tag lets you add documentation to your scripts. Documentation is displayed as a hover tooltip in the editor when you hover over a function or run handle that references the script.

The doc block is ignored at runtime — it produces no output and has no effect on script execution.

Syntax

{% doc %}
  Description of what this script does.

  @param {type} param_name - Description of the parameter
  @example
  {% function "handle", param_name:"value" as result %}
{% enddoc %}

Place the doc block at the top of your script, before any logic.

Tags

@description

Describes what the script does. You can also write the description as plain text at the top of the block — if no @description tag is present, the first lines of text are used as the description.

Explicit:

{% doc %}
  @description Sends a tracking event to Klaviyo.
{% enddoc %}

Implicit (no @description tag needed):

{% doc %}
  Sends a tracking event to Klaviyo.
{% enddoc %}

Both produce the same result.

@param

Documents a parameter that the script expects. Supports type annotations, optional markers, and descriptions.

Full format:

@param {string} email - The customer's email address

• {string} — parameter type (e.g. string, number, object, array, boolean)

• email — parameter name

• - The customer's email address — description

Optional parameters — wrap the name in square brackets:

@param {number} [retry_count] - Number of retries (default: 3)

Minimal format — only the name is required:

@param email

@example

Shows a usage example. Everything after @example until the next tag or end of the block is treated as example code.

@example
{% function "send_metric", email:customer.email, metric:"signup" as result %}

You can include multiple @example tags for different use cases.

Full example

Function script (handle: send_metric_to_klaviyo):

{% doc %}
  Sends a tracking event to the Klaviyo API.

  @param {string} email - Customer email address
  @param {string} metric - The metric/event name to track
  @param {string} [property] - Optional property value for the event

  @example
  {% function "send_metric_to_klaviyo", email:"[email protected]", metric:"Purchase" as result %}

  @example
  {% function "send_metric_to_klaviyo", email:customer.email, metric:"Signup", property:"Premium" as result %}
{% enddoc %}

{% json body %}
{
  "data": {
    "type": "event",
    "attributes": {
      "properties": {
        "membership": {{ property | default: "" | json }}
      },
      "metric": {
        "data": {
          "type": "metric",
          "attributes": {
            "name": {{ metric | default: "" | json }}
          }
        }
      },
      "profile": {
        "data": {
          "type": "profile",
          "attributes": {
            "email": {{ email | default: "" | json }}
          }
        }
      }
    }
  }
}
{% endjson %}

{% json request_options %}
{
  "url": "https://a.klaviyo.com/client/events/?company_id={{KLAVIYO_TOKEN}}",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Accept": "application/json",
    "Revision": "2024-05-15"
  },
  "body": {{ body | json }}
}
{% endjson %}
{% http url:request_options.url, method:request_options.method, body:request_options.body, headers:request_options.headers as response %}
{% return response %}

When you hover over "send_metric_to_klaviyo" in another script, the editor displays:

• The script name

• The description

• A list of parameters with types and descriptions

• Usage examples

Editor integration

The doc block is syntax highlighted in the editor:

• @param, @description, @example tags are displayed in bold green

• All other content is displayed in grey

This makes documentation blocks visually distinct from executable code.