From 71f61d0bffd7713c9ac1eda3bd11778495121c99 Mon Sep 17 00:00:00 2001 From: leynos Date: Sun, 26 Jul 2026 19:10:09 +0200 Subject: [PATCH 1/2] Document footnote parsing entry points (#367) Add `///` doc comments to `parse_definition` and `is_definition_continuation` in `src/footnotes/parsing.rs`, describing their inputs, return values, and the definition/continuation grammar they encode. These `pub(super)` helpers form the footnotes module's parsing interface, consumed across the renumber and lists submodules, and now carry a documented contract. Closes #367 Co-Authored-By: Claude Opus 4.8 (1M context) --- src/footnotes/parsing.rs | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/footnotes/parsing.rs b/src/footnotes/parsing.rs index 88a2007d..030d180a 100644 --- a/src/footnotes/parsing.rs +++ b/src/footnotes/parsing.rs @@ -21,6 +21,15 @@ pub(super) struct DefinitionParts<'a> { pub(super) rest: &'a str, } +/// Parses a footnote definition line into its constituent [`DefinitionParts`]. +/// +/// A definition matches [`DEF_RE`]: an optional blockquote prefix (`>` +/// markers with surrounding whitespace), a `[^N]:` marker bearing a decimal +/// footnote number, and the trailing text following the colon. The borrowed +/// `prefix` and `rest` fields point into `line`. +/// +/// Returns [`None`] when `line` is not a definition, or when the captured +/// number does not parse as a [`usize`]. pub(super) fn parse_definition(line: &str) -> Option> { DEF_RE.captures(line).and_then(|caps| { let number = caps["num"].parse::().ok()?; @@ -32,6 +41,12 @@ pub(super) fn parse_definition(line: &str) -> Option> { }) } +/// Reports whether `line` continues the preceding footnote definition. +/// +/// A continuation is any line whose first character is whitespace, marking +/// indented body text that belongs to the definition above it rather than +/// beginning a new construct. An empty `line` has no leading character and so +/// returns `false`. #[inline] pub(super) fn is_definition_continuation(line: &str) -> bool { line.chars().next().is_some_and(char::is_whitespace) From cb89fdd4afd536f59af308f81ddea00efe4a61a8 Mon Sep 17 00:00:00 2001 From: leynos Date: Mon, 27 Jul 2026 20:04:33 +0200 Subject: [PATCH 2/2] Add input/output examples to footnote parsing docs Address review feedback: per the AGENTS.md convention that function documentation include a clear usage-and-outcome example, add `# Examples` sections to `parse_definition` and `is_definition_continuation`. The examples use `text` code blocks (these `pub(super)` helpers are not part of the public doctest surface) and show representative inputs alongside their outcomes, making the whitespace and marker contracts immediate. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/footnotes/parsing.rs | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/footnotes/parsing.rs b/src/footnotes/parsing.rs index 030d180a..080f37f7 100644 --- a/src/footnotes/parsing.rs +++ b/src/footnotes/parsing.rs @@ -30,6 +30,14 @@ pub(super) struct DefinitionParts<'a> { /// /// Returns [`None`] when `line` is not a definition, or when the captured /// number does not parse as a [`usize`]. +/// +/// # Examples +/// +/// ```text +/// "[^1]: See the note." => Some { prefix: "", number: 1, rest: " See the note." } +/// "> > [^2]: Nested." => Some { prefix: "> > ", number: 2, rest: " Nested." } +/// " indented body" => None // no `[^N]:` marker +/// ``` pub(super) fn parse_definition(line: &str) -> Option> { DEF_RE.captures(line).and_then(|caps| { let number = caps["num"].parse::().ok()?; @@ -47,6 +55,15 @@ pub(super) fn parse_definition(line: &str) -> Option> { /// indented body text that belongs to the definition above it rather than /// beginning a new construct. An empty `line` has no leading character and so /// returns `false`. +/// +/// # Examples +/// +/// ```text +/// " continued text" => true // leading whitespace +/// "\tcontinued text" => true // leading tab +/// "[^1]: definition" => false // starts a new definition +/// "" => false // no leading character +/// ``` #[inline] pub(super) fn is_definition_continuation(line: &str) -> bool { line.chars().next().is_some_and(char::is_whitespace)