# `Kreuzberg.DocumentTextAnnotation`
[🔗](https://github.com/kreuzberg-dev/kreuzberg/blob/main/lib/kreuzberg/document_structure.ex#L1)

Inline text annotation with byte-range formatting and links.

Annotations reference byte offsets into a node's text content,
enabling precise identification of formatted regions.

## Fields

  * `:start` - Start byte offset (inclusive)
  * `:end` - End byte offset (exclusive)
  * `:kind` - Annotation type (bold, italic, link, etc.)
  * `:url` - URL for link annotations (nil for other types)

## Examples

    iex> annotation = %Kreuzberg.DocumentTextAnnotation{
    ...>   start: 0,
    ...>   end: 5,
    ...>   kind: "bold"
    ...> }
    iex> annotation.kind
    "bold"

# `annotation_kind`

```elixir
@type annotation_kind() ::
  :bold
  | :italic
  | :underline
  | :strikethrough
  | :code
  | :subscript
  | :superscript
  | :link
```

# `t`

```elixir
@type t() :: %Kreuzberg.DocumentTextAnnotation{
  end: non_neg_integer(),
  kind: String.t(),
  start: non_neg_integer(),
  url: String.t() | nil
}
```

# `from_map`

```elixir
@spec from_map(map()) :: t()
```

Creates a DocumentTextAnnotation struct from a map.

Converts a plain map (typically from NIF/Rust) into a proper struct.

## Parameters

  * `data` - A map containing annotation fields

## Returns

A `DocumentTextAnnotation` struct with properly typed fields.

## Examples

    iex> annotation_map = %{
    ...>   "start" => 0,
    ...>   "end" => 5,
    ...>   "kind" => "bold"
    ...> }
    iex> annotation = Kreuzberg.DocumentTextAnnotation.from_map(annotation_map)
    iex> annotation.kind
    "bold"

# `link?`

```elixir
@spec link?(t()) :: boolean()
```

Check if this is a link annotation.

## Parameters

  * `annotation` - A `DocumentTextAnnotation` struct

## Returns

Boolean indicating whether the annotation is a link.

## Examples

    iex> annotation = %Kreuzberg.DocumentTextAnnotation{kind: "link", url: "https://example.com"}
    iex> Kreuzberg.DocumentTextAnnotation.link?(annotation)
    true

# `readable_kind`

```elixir
@spec readable_kind(t()) :: String.t()
```

Get human-readable annotation kind name.

Converts annotation kind to a display-friendly string.

## Parameters

  * `annotation` - A `DocumentTextAnnotation` struct

## Returns

A human-readable string representation of the annotation kind.

## Examples

    iex> annotation = %Kreuzberg.DocumentTextAnnotation{kind: "bold"}
    iex> Kreuzberg.DocumentTextAnnotation.readable_kind(annotation)
    "Bold"

# `to_map`

```elixir
@spec to_map(t()) :: map()
```

Converts a DocumentTextAnnotation struct to a map.

Useful for serialization and passing to external systems.

## Parameters

  * `annotation` - A `DocumentTextAnnotation` struct

## Returns

A map with string keys representing all fields.

## Examples

    iex> annotation = %Kreuzberg.DocumentTextAnnotation{
    ...>   start: 0,
    ...>   end: 5,
    ...>   kind: "bold"
    ...> }
    iex> Kreuzberg.DocumentTextAnnotation.to_map(annotation)
    %{"start" => 0, "end" => 5, "kind" => "bold", "url" => nil}

---

*Consult [api-reference.md](api-reference.md) for complete listing*