# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.datajet-app.com/liquid/tags/doc.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.