# Document Snippets and Blocks with `{% doc %}`

Every snippet and every statically rendered block must start with a `{% doc %}` header. The theme editor, language server, and `docs-to-context` extractor all read these tags to build parameter hints and auto-complete.

```liquid
{% doc %}
  Renders a responsive image, optionally wrapped in a link.

  @param {image} image - The image to be rendered
  @param {string} [url] - Optional destination URL
  @param {string} [css_class] - Optional class added to the wrapper
  @param {number} [width] - Max resolution width
  @param {number} [height] - Max resolution height
  @param {string} [crop] - Crop position (center, top, bottom, left, right)

  @example
  {% render 'image', image: product.featured_image %}
  {% render 'image',
    image: product.featured_image,
    url: product.url,
    width: 1200,
    crop: 'center'
  %}
{% enddoc %}
```

## Syntax

- **`@param {type} name - description`** — required parameter.
- **`@param {type} [name] - description`** — optional parameter (square brackets around the name).
- **`@param {type} [name=default] - description`** — optional with a default value.
- **`@example`** — one or more example `{% render %}` / `{% content_for %}` calls.

## Supported `{type}` values

`string`, `number`, `boolean`, `image`, `product`, `variant`, `collection`, `article`, `blog`, `page`, `link`, `metaobject`, `object`, `array`.

## Rules

- **Snippets** in `snippets/` — `{% doc %}` is recommended. `docs-to-context` extracts these into `.context/components/`.
- **Static blocks** rendered via `{% content_for 'block' %}` — `{% doc %}` is **required**. See `liquid-static-blocks.md`.
- Document every parameter the snippet reads from its arguments. Do not document globals (`product`, `section`, `settings`) — those are scope, not parameters.
- Keep descriptions short — one line each. Put longer notes in the free-form area above `@param`.
- `{% doc %}` content is parsed but never rendered, so there's zero runtime cost.

## Anti-patterns

```liquid
{% comment %} BAD: comment instead of doc tag — not machine-readable {% endcomment %}
{% comment %}
  Renders an image. Params: image, url, width.
{% endcomment %}

{% comment %} BAD: missing types {% endcomment %}
{% doc %}
  @param image - the image
  @param url - optional link
{% enddoc %}

{% comment %} BAD: documenting scope globals as params {% endcomment %}
{% doc %}
  @param {product} product - the product object
  @param {section} section - the section
{% enddoc %}
```