---
title: "Find which YAML node owns a comment in Rust"
url: https://recursiveai.org/oneyaml/rust/cookbook/explain-yaml-comment-owner/
description: "Use Rust to explain a YAML comment’s owner and see why an indented note belongs to a nested mapping instead of the key below it."
version: "1.2.0"
---

# Find which YAML node owns a comment in Rust

**oneyaml** is a free, open-source YAML library for Rust from Recursive AI. MIT or Apache-2.0, no unsafe code.

[crates.io](https://crates.io/crates/oneyaml) · [GitHub](https://github.com/recursive-ai-oss/oneyaml-rust) · [Docs](https://recursiveai.org/oneyaml/rust/docs/) · [Download example (.zip)](https://recursiveai.org/oneyaml/rust/cookbook/explain-yaml-comment-owner/explain-yaml-comment-owner.zip)

Use `explain_comment` to see whether a note belongs to the map above it or the key below it.

```shell
cargo add oneyaml
```

```rust
use oneyaml::{CommentOwner, Document};

fn main() {
    let yaml = concat!(
        "web:\n  port: 8080\n  # proxy note\n",
        "jobs: 2\n",
    );
    let doc = Document::parse(yaml)
        .expect("valid YAML");
    let info = doc.explain_comment(
        doc.comment_ids()[0]
    ).expect("explain comment");
    let web = doc.get("web").expect("web map");
    assert_eq!(info.owner(),
        CommentOwner::Footer(web.id()));
    println!("{}: footer of web", info.text());
    println!("Rule {}", info.rule().number());
}
```

Unzip [the example](https://recursiveai.org/oneyaml/rust/cookbook/explain-yaml-comment-owner/explain-yaml-comment-owner.zip), then `cargo run`.

Requires Rust 1.85 or later. The snippet identifies the owner and attachment rule:

```text
# proxy note: footer of web
Rule 6
```

## The full program

The full program also adds `# worker count` on the `jobs` line, checks that it belongs to `jobs`, and prints the rule summary for both comments. `explain_comment` returns `EditError::StaleNode` if the ID refers to a comment removed by an edit or to another document.

```rust
use oneyaml::{CommentOwner, Document};

fn main() {
    let yaml = concat!(
        "web:\n  port: 8080\n  # proxy note\n",
        "jobs: 2 # worker count\n",
    );
    let doc = Document::parse(yaml)
        .expect("valid YAML");
    let info = doc.explain_comment(
        doc.comment_ids()[0]
    ).expect("explain comment");
    let web = doc.get("web").expect("web map");
    assert_eq!(info.owner(),
        CommentOwner::Footer(web.id()));
    println!("{}: footer of web", info.text());
    println!("Rule {}", info.rule().number());

    let jobs = doc.get("jobs").expect("jobs value")
        .key().expect("jobs key").id();
    let trailing = doc.explain_comment(doc.comment_ids()[1])
        .expect("explain worker count");
    assert_eq!(trailing.owner(), CommentOwner::Trailing(jobs));

    // Inspect the explanation for each comment in the document.
    for info in doc.explain_comments().expect("explain all comments") {
        println!("{}: {}", info.text(), info.rule().summary());
    }
}
```

`cargo run` prints:

```text
# proxy note: footer of web
Rule 6
# proxy note: collection footer: after the last child, deeper than what follows
# worker count: trailing: after content on its line
```

## Related recipes

- [Reattach a YAML comment to another key](https://recursiveai.org/oneyaml/rust/cookbook/move-yaml-comment-between-keys/)
- [Find the byte span of a YAML field](https://recursiveai.org/oneyaml/rust/cookbook/track-yaml-field-byte-spans/)

## The short answer

Call `doc.explain_comment(id)` before editing. Its `owner()` says which node or document boundary owns the comment, and `rule()` says why. Here the `# proxy note` line is indented under `web`. The explanation is `Footer(web.id())`, rule 6. The note doesn’t lead `jobs`, even though `jobs` is the next key in the text.

## What are the rules for indentation in YAML comments?

[YAML itself doesn’t attach comments to nodes](https://yaml.org/spec/1.2.2/#66-comments); the rules here are oneyaml-rust’s. In oneyaml-rust, an own-line comment after the last child of a block collection, farther right than the content that comes next, can be the footer of that collection. In this example, `port` is the last child of `web`, the note starts two spaces in, and `jobs` starts at the left margin. That’s the shape covered by rule 6 in the [comment attachment rules](https://recursiveai.org/oneyaml/rust/docs/comment-attachment/).

Here, *footer* means a comment owned by the end of the nested collection, not by the end of the whole file. A same-line comment after `port: 8080` would instead be trailing on that mapping entry (rule 5). Comparing the rule and owner is more reliable than guessing from the closest line when a note sits between two sections.

## How can you tell whether a YAML comment belongs to a key or to the whole map?

Look at `owner()` first. For a mapping entry, `Leading(id)` or `Trailing(id)` names the key node. `Footer(id)` names the collection itself. `DocumentHeader` and `DocumentFooter` don’t name a node. For diagnostics, [the explanation](https://github.com/recursive-ai-oss/oneyaml-rust/blob/14445615f5a5b2895fdaa1da7719584ef15d9d6b/crates/oneyaml/src/document/comments.rs#L174-L212) also gives the comment text, its UTF-8 byte span, and an optional span for the owner. Use those spans if you need to highlight the two locations in the same source, rather than searching for a matching fragment of text.
