# 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

```liquid
{% 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:**

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

**Implicit (no @description tag needed):**

```liquid
{% 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:**

```liquid
@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:

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

**Minimal format** — only the name is required:

```liquid
@param email
```

#### @example

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

```liquid
@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`):

```liquid
{% 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:"user@example.com", 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.