miniextendr_macros/

roxygen.rs

//! Roxygen tag extraction and processing for R wrapper generation.
//!
//! This module extracts roxygen2-style tags (e.g., `@param`, `@examples`) from Rust
//! doc comments and propagates them to generated R wrapper code.
//!
//! # Usage
//!
//! In Rust doc comments, use roxygen2 tags:
//!
//! ```rust,ignore
//! /// @param x A numeric input.
//! /// @return The squared value.
//! /// @examples
//! /// square(4)
//! #[miniextendr]
//! pub fn square(x: f64) -> f64 { x * x }
//! ```
//!
//! # R Package Configuration
//!
//! For roxygen2 to process multiline tags correctly, add this to your `DESCRIPTION` file:
//!
//! ```text
//! Roxygen: list(markdown = TRUE)
//! ```

use std::collections::HashSet;

/// Tags that allow multi-line content (continuation lines appended).
/// All other tags are treated as single-line.
const MULTILINE_TAGS: &[&str] = &[
    "examples",
    "description",
    "details",
    "return",
    "returns",
    "param",
    "note",
    "seealso",
    "section",
    "format",
    "references",
    "slot",
    "field",
    "value", // synonym for return
    "prop",  // S7 property documentation (roxygen2 8.0.0+)
];

/// Check if a tag name supports multi-line content.
fn is_multiline_tag(tag: &str) -> bool {
    // Extract the tag name from "@tagname ..." or "@tagname"
    let tag_name = tag
        .strip_prefix('@')
        .and_then(|rest| rest.split_whitespace().next())
        .unwrap_or("");
    MULTILINE_TAGS.contains(&tag_name)
}

/// Extract roxygen tag lines (starting with '@') from Rust doc attributes.
///
/// Most tags capture only a single line. Multi-line tags like `@examples`,
/// `@description`, `@param`, and `@return` append continuation lines.
///
/// For R6 methods, if no explicit tags are found, the first doc comment paragraph
/// is auto-converted to `@description`.
pub(crate) fn roxygen_tags_from_attrs(attrs: &[syn::Attribute]) -> Vec<String> {
    roxygen_tags_from_attrs_impl(attrs, false)
}

/// Extract roxygen tags with optional auto-description for impl methods.
///
/// If `auto_description = true` and no explicit `@tag` is found, the first
/// paragraph of regular doc comments is converted to `@description`.
///
/// Used for all class systems (R6, S3, S4, S7, Env) to automatically
/// convert Rust doc comments into roxygen `@description` tags.
pub(crate) fn roxygen_tags_from_attrs_for_r6_method(attrs: &[syn::Attribute]) -> Vec<String> {
    roxygen_tags_from_attrs_impl(attrs, true)
}

/// Core implementation of roxygen tag extraction from `#[doc = "..."]` attributes.
///
/// Walks through doc attributes line by line. Lines starting with `@` begin a new tag.
/// Continuation lines are appended only if the current tag is multiline-capable.
///
/// When `auto_description` is true and no `@tag` lines are found, the first paragraph
/// of regular doc comments is auto-converted to `@description`.
///
/// Also auto-generates `@title` from the implicit title (first sentence) when tags
/// are present but `@title` is missing, and `@description` when `@name` is present
/// but `@description` is missing.
fn roxygen_tags_from_attrs_impl(attrs: &[syn::Attribute], auto_description: bool) -> Vec<String> {
    let mut tags = Vec::new();
    let mut regular_docs = Vec::new();
    // Track whether we have seen doc content followed by a non-doc attribute.
    // When that happens, subsequent bare prose must NOT continue into any open
    // multiline tag (it would corrupt @examples / @details / @return blocks).
    // Instead we reset the multiline-continuation context so the trailing prose
    // is treated as new regular_docs material (if tags is still empty) or is
    // simply ignored as a continuation.
    let mut interrupted_by_non_doc = false;

    for attr in attrs {
        if !attr.path().is_ident("doc") {
            // Non-doc attribute between doc runs — set interruption flag if we
            // have already collected some doc content.
            if !tags.is_empty() || !regular_docs.is_empty() {
                interrupted_by_non_doc = true;
            }
            continue;
        }
        let syn::Meta::NameValue(nv) = &attr.meta else {
            continue;
        };
        let syn::Expr::Lit(expr_lit) = &nv.value else {
            continue;
        };
        let syn::Lit::Str(lit) = &expr_lit.lit else {
            continue;
        };
        for line in lit.value().lines() {
            let trimmed = line.trim_start();
            if trimmed.starts_with('@') {
                // New tag starts — interruption no longer relevant for tags
                interrupted_by_non_doc = false;
                tags.push(trimmed.to_string());
            } else if !trimmed.is_empty() {
                if tags.is_empty() {
                    // Before any @tags - collect as regular docs
                    // (allowed even after an interruption — user prose, not tag continuation)
                    regular_docs.push(trimmed.to_string());
                } else if interrupted_by_non_doc {
                    // Bare prose after a non-doc attribute interruption:
                    // do NOT append to any open multiline tag — that would
                    // corrupt @examples / @details / @return content.
                    // The prose is dropped for tag-continuation purposes.
                } else if let Some(last) = tags.last_mut()
                    && is_multiline_tag(last)
                {
                    // Continuation line for multi-line tags only
                    last.push('\n');
                    last.push_str(trimmed);
                }
                // Single-line tags: ignore continuation lines
            }
        }
    }

    // Check which tags are present
    let tag_names_set = tag_names(&tags);
    let has_name = tag_names_set.contains("name") || tag_names_set.contains("rdname");
    let has_title = tag_names_set.contains("title");
    let has_description = tag_names_set.contains("description");
    let has_any_tags = !tags.is_empty();

    // Auto-generate @title from implicit title if:
    // - We have @name but no @title, OR
    // - We have any tags (like @param/@return) but no @title (user is writing roxygen docs)
    // Use implicit_title_from_attrs which respects paragraph breaks
    if (has_name || has_any_tags)
        && !has_title
        && let Some(title) = implicit_title_from_attrs(attrs)
    {
        tags.insert(0, format!("@title {}", title));
    }

    // Auto-generate @description from implicit description (second paragraph) if:
    // - We have @name or any tags (like @param/@return) but no @description
    // Mirrors the @title auto-generation condition above
    if (has_name || has_any_tags)
        && !has_description
        && let Some(desc) = implicit_description_from_attrs(attrs)
    {
        // Insert after @title if present, otherwise at start
        let insert_pos = if tags.first().is_some_and(|t| t.starts_with("@title")) {
            1
        } else {
            0
        };
        tags.insert(insert_pos, format!("@description {}", desc));
    }

    // Auto-generate @details from implicit details (paragraphs 3+) if:
    // - We have @name or any tags but no explicit @details
    // - There are 3+ free-form paragraphs before the first @tag
    let has_details = tag_names(&tags).contains("details");
    if (has_name || has_any_tags)
        && !has_details
        && let Some(details) = implicit_details_from_attrs(attrs)
    {
        // Insert after @title + @description if present
        let insert_pos = tags
            .iter()
            .take_while(|t| t.starts_with("@title") || t.starts_with("@description"))
            .count();
        tags.insert(insert_pos, format!("@details {}", details));
    }

    // Auto-description for impl methods that have no explicit @tags.
    // Follows roxygen2 convention: paragraph 1 → @title, paragraph 2 → @description,
    // paragraphs 3+ → @details.  The three implicit_*_from_attrs helpers parse the
    // raw attrs so they correctly handle paragraph boundaries even when there is no
    // blank-line separator encoded in the pre-collected `regular_docs`.
    if auto_description && tags.is_empty() && !regular_docs.is_empty() {
        if let Some(title) = implicit_title_from_attrs(attrs) {
            tags.push(format!("@title {}", title));
        }
        if let Some(desc) = implicit_description_from_attrs(attrs) {
            tags.push(format!("@description {}", desc));
        }
        if let Some(details) = implicit_details_from_attrs(attrs) {
            tags.push(format!("@details {}", details));
        }
    }

    tags
}

/// Render roxygen tag lines as "#' ..." comment lines.
///
/// Multiline tags (containing '\n') are split into separate `#'` lines.
pub(crate) fn format_roxygen_tags(tags: &[String]) -> String {
    if tags.is_empty() {
        return String::new();
    }
    let mut out = String::new();
    for tag in tags {
        for line in tag.lines() {
            out.push_str("#' ");
            out.push_str(line);
            out.push('\n');
        }
    }
    out
}

/// Push roxygen tag lines into a vector of R wrapper lines.
///
/// Multiline tags (containing '\n') are split into separate `#'` lines.
pub(crate) fn push_roxygen_tags(lines: &mut Vec<String>, tags: &[String]) {
    for tag in tags {
        for line in tag.lines() {
            lines.push(format!("#' {}", line));
        }
    }
}

/// Like [`push_roxygen_tags`] but takes `&[&str]` for filtered tag slices.
pub(crate) fn push_roxygen_tags_str(lines: &mut Vec<String>, tags: &[&str]) {
    for tag in tags {
        for line in tag.lines() {
            lines.push(format!("#' {}", line));
        }
    }
}

/// Return true if the tag list contains a specific roxygen tag.
///
/// Supports both single-word tags (e.g., `"export"`, `"noRd"`) and
/// multi-word tags (e.g., `"keywords internal"`). For single-word tags,
/// matches the first word after `@`. For multi-word tags, matches the
/// full content after `@` (trimmed).
pub(crate) fn has_roxygen_tag(tags: &[String], tag: &str) -> bool {
    if tag.contains(' ') {
        // Multi-word tag: match the full content after @
        tags.iter().any(|t| {
            t.trim_start()
                .strip_prefix('@')
                .is_some_and(|rest| rest.trim() == tag)
        })
    } else {
        tag_names(tags).contains(tag)
    }
}

/// Build a roxygen `@source` traceability line for a class method.
///
/// Returns `"#' @source Generated by miniextendr from \`Type::method\`"`.
/// Use this wherever a class-generator needs to emit a source-provenance
/// comment linking the generated R wrapper back to the originating Rust
/// `impl` block method.
pub(crate) fn method_source_tag(type_ident: &syn::Ident, method_ident: &syn::Ident) -> String {
    format!(
        "#' @source Generated by miniextendr from `{}::{}`",
        type_ident, method_ident
    )
}

/// Build a roxygen `@source` traceability line for a class definition.
///
/// Returns ``"#' @source Generated by miniextendr from Rust type `Type`"``.
/// Companion to [`method_source_tag`] for class-level documentation blocks.
pub(crate) fn class_source_tag(type_ident: &syn::Ident) -> String {
    format!(
        "#' @source Generated by miniextendr from Rust type `{}`",
        type_ident
    )
}

/// Extract the set of tag names from a list of roxygen tag strings.
///
/// Each tag string is expected to start with `@tagname`. Returns a set of
/// the tag names (without the `@` prefix).
fn tag_names(tags: &[String]) -> HashSet<&str> {
    let mut names = HashSet::new();
    for tag in tags {
        let trimmed = tag.trim_start();
        let name = trimmed
            .strip_prefix('@')
            .and_then(|rest| rest.split_whitespace().next());
        if let Some(name) = name {
            names.insert(name);
        }
    }
    names
}

/// Find the value of a specific roxygen tag (e.g., "title" for `@title ...`).
///
/// Returns `None` if the tag is not present or has no value.
#[cfg_attr(not(feature = "doc-lint"), allow(dead_code))]
pub(crate) fn find_tag_value<'a>(tags: &'a [String], tag_name: &str) -> Option<&'a str> {
    for tag in tags {
        let trimmed = tag.trim_start();
        if let Some(rest) = trimmed.strip_prefix('@') {
            let mut parts = rest.splitn(2, |c: char| c.is_whitespace());
            if let Some(name) = parts.next()
                && name == tag_name
            {
                // Get the value (everything after the tag name)
                return parts.next().map(|s| s.trim());
            }
        }
    }
    None
}

/// Normalize text for comparison: lowercase, collapse whitespace, strip trailing punctuation.
///
/// Used by `doc_conflict_warnings` to compare explicit `@title`/`@description` values
/// with implicit values derived from the doc comment structure. Normalization ensures
/// minor formatting differences (extra spaces, trailing periods) don't trigger false warnings.
#[cfg_attr(not(feature = "doc-lint"), allow(dead_code))]
fn normalize_for_comparison(s: &str) -> String {
    let lower = s.to_lowercase();
    let mut result = String::new();
    for word in lower.split_whitespace() {
        if !result.is_empty() {
            result.push(' ');
        }
        result.push_str(word);
    }
    result.truncate(
        result
            .trim_end_matches(|c: char| c.is_ascii_punctuation())
            .len(),
    );
    result
}

/// Extract the implicit title from doc attributes (first sentence, up to first `.` or newline).
///
/// Returns `None` if there are no doc comments or if docs start with a `@tag`.
#[cfg_attr(not(feature = "doc-lint"), allow(dead_code))]
pub(crate) fn implicit_title_from_attrs(attrs: &[syn::Attribute]) -> Option<String> {
    let mut lines = Vec::new();

    for attr in attrs {
        if !attr.path().is_ident("doc") {
            continue;
        }
        let syn::Meta::NameValue(nv) = &attr.meta else {
            continue;
        };
        let syn::Expr::Lit(expr_lit) = &nv.value else {
            continue;
        };
        let syn::Lit::Str(lit) = &expr_lit.lit else {
            continue;
        };

        let content = lit.value();
        let trimmed = content.trim();

        // If we hit a @tag before any content, there's no implicit title
        if trimmed.starts_with('@') {
            if lines.is_empty() {
                return None;
            }
            break;
        }

        // Empty line ends first sentence for title extraction
        if trimmed.is_empty() {
            break;
        }

        // Check if this line contains a sentence-ending period
        if let Some(pos) = trimmed.find(". ") {
            lines.push(trimmed[..pos].to_string());
            break;
        } else if trimmed.ends_with('.') {
            lines.push(trimmed.trim_end_matches('.').to_string());
            break;
        } else {
            lines.push(trimmed.to_string());
        }
    }

    if lines.is_empty() {
        None
    } else {
        Some(lines.join(" "))
    }
}

/// Extract the implicit description from doc attributes (second paragraph).
///
/// In roxygen2, the first paragraph is the title and the second paragraph is the
/// description. This function skips the first paragraph (up to the first blank line)
/// and returns the second paragraph.
///
/// Returns `None` if there is no second paragraph, no doc comments, or if docs
/// start with a `@tag`.
#[cfg_attr(not(feature = "doc-lint"), allow(dead_code))]
pub(crate) fn implicit_description_from_attrs(attrs: &[syn::Attribute]) -> Option<String> {
    let mut lines = Vec::new();
    let mut found_first_paragraph = false;
    let mut in_gap = false;

    for attr in attrs {
        if !attr.path().is_ident("doc") {
            continue;
        }
        let syn::Meta::NameValue(nv) = &attr.meta else {
            continue;
        };
        let syn::Expr::Lit(expr_lit) = &nv.value else {
            continue;
        };
        let syn::Lit::Str(lit) = &expr_lit.lit else {
            continue;
        };

        let content = lit.value();
        let trimmed = content.trim();

        // If we hit a @tag, stop
        if trimmed.starts_with('@') {
            break;
        }

        if !found_first_paragraph {
            // Still in the first paragraph (title)
            if trimmed.is_empty() {
                // Blank line — first paragraph ended, now in the gap
                found_first_paragraph = true;
                in_gap = true;
            }
            // Non-empty lines before first blank are title — skip
        } else if in_gap {
            // Between paragraphs — skip blank lines
            if !trimmed.is_empty() {
                // Start of second paragraph
                in_gap = false;
                lines.push(trimmed.to_string());
            }
        } else {
            // In second paragraph
            if trimmed.is_empty() {
                // End of second paragraph
                break;
            }
            lines.push(trimmed.to_string());
        }
    }

    if lines.is_empty() {
        None
    } else {
        Some(lines.join(" "))
    }
}

/// Extract the implicit details from doc attributes (paragraphs 3+).
///
/// In roxygen2, paragraph 1 is the title, paragraph 2 is the description,
/// and paragraphs 3+ become `\details{}`. This function skips paragraphs 1 and 2
/// and returns the remaining free-form paragraphs (before the first `@tag`)
/// joined with `\n\n`.
///
/// Returns `None` if there are fewer than 3 paragraphs, no doc comments, or if
/// docs start with a `@tag`.
#[cfg_attr(not(feature = "doc-lint"), allow(dead_code))]
pub(crate) fn implicit_details_from_attrs(attrs: &[syn::Attribute]) -> Option<String> {
    // paragraph_index: 0=title, 1=description, 2+=details
    let mut paragraph_index: usize = 0;
    let mut in_gap = false;
    let mut detail_paragraphs: Vec<Vec<String>> = Vec::new();
    let mut current_paragraph: Vec<String> = Vec::new();

    for attr in attrs {
        if !attr.path().is_ident("doc") {
            continue;
        }
        let syn::Meta::NameValue(nv) = &attr.meta else {
            continue;
        };
        let syn::Expr::Lit(expr_lit) = &nv.value else {
            continue;
        };
        let syn::Lit::Str(lit) = &expr_lit.lit else {
            continue;
        };

        let content = lit.value();
        let trimmed = content.trim();

        // Stop at the first @tag
        if trimmed.starts_with('@') {
            break;
        }

        if trimmed.is_empty() {
            // Blank line — paragraph boundary
            if !in_gap {
                // End of the current paragraph
                if paragraph_index >= 2 && !current_paragraph.is_empty() {
                    detail_paragraphs.push(std::mem::take(&mut current_paragraph));
                } else {
                    current_paragraph.clear();
                }
                paragraph_index += 1;
                in_gap = true;
            }
            // Multiple blank lines in a row: stay in gap
        } else {
            // Non-empty line
            in_gap = false;
            if paragraph_index >= 2 {
                current_paragraph.push(trimmed.to_string());
            }
            // paragraphs 0 (title) and 1 (description) are skipped
        }
    }

    // Handle a details paragraph that isn't terminated by a blank line / @tag
    if paragraph_index >= 2 && !current_paragraph.is_empty() {
        detail_paragraphs.push(current_paragraph);
    }

    if detail_paragraphs.is_empty() {
        None
    } else {
        let joined: Vec<String> = detail_paragraphs.into_iter().map(|p| p.join(" ")).collect();
        Some(joined.join("\n\n"))
    }
}

/// Check for conflicts between explicit `@title`/`@description` tags and implicit values.
///
/// When the `doc-lint` feature is enabled, returns tokens that generate compile-time
/// deprecation warnings if explicit roxygen tags differ from the implicit values
/// derived from the doc comment structure.
///
/// The returned tokens should be appended to the macro expansion output.
#[cfg(feature = "doc-lint")]
pub(crate) fn doc_conflict_warnings(
    attrs: &[syn::Attribute],
    _span: proc_macro2::Span,
) -> proc_macro2::TokenStream {
    use quote::quote;

    let tags = roxygen_tags_from_attrs(attrs);
    let mut warnings = proc_macro2::TokenStream::new();

    // Check @title conflict
    if let Some(explicit) = find_tag_value(&tags, "title")
        && let Some(implicit) = implicit_title_from_attrs(attrs)
        && normalize_for_comparison(explicit) != normalize_for_comparison(&implicit)
    {
        let msg = format!(
            "miniextendr doc-lint: explicit @title differs from first doc line. \
             R's roxygen2 uses the first line as the title. \
             implicit: \"{}\", explicit @title: \"{}\"",
            implicit, explicit
        );
        warnings.extend(quote! {
            const _: () = {
                #[deprecated(note = #msg)]
                #[doc(hidden)]
                #[allow(dead_code)]
                const MINIEXTENDR_DOC_LINT_TITLE: () = ();
                let _ = MINIEXTENDR_DOC_LINT_TITLE;
            };
        });
    }

    // Check @description conflict
    if let Some(explicit) = find_tag_value(&tags, "description")
        && let Some(implicit) = implicit_description_from_attrs(attrs)
        && normalize_for_comparison(explicit) != normalize_for_comparison(&implicit)
    {
        let msg = format!(
            "miniextendr doc-lint: explicit @description differs from first paragraph. \
             R's roxygen2 uses the first paragraph as the description. \
             implicit: \"{}\", explicit @description: \"{}\"",
            implicit, explicit
        );
        warnings.extend(quote! {
            const _: () = {
                #[deprecated(note = #msg)]
                #[doc(hidden)]
                #[allow(dead_code)]
                const MINIEXTENDR_DOC_LINT_DESC: () = ();
                let _ = MINIEXTENDR_DOC_LINT_DESC;
            };
        });
    }

    warnings
}

/// No-op when doc-lint feature is disabled.
#[cfg(not(feature = "doc-lint"))]
pub(crate) fn doc_conflict_warnings(
    _attrs: &[syn::Attribute],
    _span: proc_macro2::Span,
) -> proc_macro2::TokenStream {
    proc_macro2::TokenStream::new()
}

/// Roxygen tags that only make sense on individual methods, not on impl blocks.
///
/// - `@param` — impl blocks have no parameters.
/// - `@return` / `@returns` — impl blocks have no return value.
/// - `@examples` — examples belong on the method that is being demonstrated.
/// - `@export` — redundant: export for class-level docs is handled by
///   [`ClassDocBuilder`], which emits `@export` based on the impl block's
///   `internal` / `noexport` attrs, not on user-supplied roxygen.
const METHOD_ONLY_TAGS: &[&str] = &["param", "return", "returns", "examples", "export"];

/// Extract the tag name from a roxygen line (everything between `@` and the
/// first whitespace character). Returns `None` for lines that don't start with
/// a tag.
fn roxygen_tag_name(tag: &str) -> Option<&str> {
    let rest = tag.trim_start().strip_prefix('@')?;
    let end = rest.find(char::is_whitespace).unwrap_or(rest.len());
    Some(&rest[..end])
}

/// Filter out method-specific roxygen tags from impl-block-level docs and emit
/// compile warnings for each stripped tag.
///
/// Method-specific tags (`@param`, `@return`, `@returns`, `@examples`,
/// `@export`) on an impl block are meaningless — they belong on individual
/// methods, or (for `@export`) are emitted by [`ClassDocBuilder`]. When users
/// put them on impl blocks, the tags leak into the class-level Rd file where
/// R CMD check warns about "documented arguments not in \\usage" and similar.
///
/// Returns the filtered tags and a TokenStream of deprecation warnings for
/// each stripped tag. The caller should append the warnings to its output so
/// the user sees them at compile time.
pub(crate) fn strip_method_tags(
    tags: &[String],
    type_name: &str,
    span: proc_macro2::Span,
) -> (Vec<String>, proc_macro2::TokenStream) {
    use quote::quote_spanned;

    let mut filtered = Vec::new();
    let mut warnings = proc_macro2::TokenStream::new();
    let mut warning_id: usize = 0;

    for tag in tags {
        let Some(name) = roxygen_tag_name(tag) else {
            filtered.push(tag.clone());
            continue;
        };
        if !METHOD_ONLY_TAGS.contains(&name) {
            filtered.push(tag.clone());
            continue;
        }
        let msg = format!(
            "miniextendr: @{} on impl block `{}` has no effect — move it to the method. Tag: {}",
            name,
            type_name,
            tag.trim()
        );
        let ident = quote::format_ident!(
            "_MINIEXTENDR_IMPL_METHOD_TAG_WARN_{}_{}",
            type_name.replace(|c: char| !c.is_alphanumeric(), "_"),
            warning_id
        );
        warning_id += 1;
        warnings.extend(quote_spanned! { span =>
            #[deprecated(note = #msg)]
            #[doc(hidden)]
            #[allow(dead_code)]
            const #ident: () = ();
        });
    }

    (filtered, warnings)
}

/// Strip roxygen tag lines from doc attributes, keeping only regular documentation.
///
/// Returns a new vector of attributes with roxygen lines removed from doc comments.
/// Non-doc attributes are passed through unchanged.
///
/// # Algorithm
///
/// Roxygen tags typically appear at the end of documentation blocks. We use a simple
/// but effective approach:
/// 1. Keep all content before the first `@tag` line
/// 2. Strip everything from the first `@tag` to the end of the roxygen region
///
/// A roxygen region ends when we see a non-empty line that doesn't start with `@`
/// and follows an empty line (paragraph break). This handles multi-paragraph tags.
pub(crate) fn strip_roxygen_from_attrs(attrs: &[syn::Attribute]) -> Vec<syn::Attribute> {
    // Collect doc attribute indices and their trimmed content
    let mut doc_info: Vec<(usize, String)> = Vec::new();
    for (i, attr) in attrs.iter().enumerate() {
        if !attr.path().is_ident("doc") {
            continue;
        }
        let syn::Meta::NameValue(nv) = &attr.meta else {
            continue;
        };
        let syn::Expr::Lit(expr_lit) = &nv.value else {
            continue;
        };
        let syn::Lit::Str(lit) = &expr_lit.lit else {
            continue;
        };
        // Trim the leading space that comes from `/// `
        doc_info.push((i, lit.value().trim_start().to_string()));
    }

    // Find roxygen line indices
    let mut roxygen_indices: std::collections::HashSet<usize> = std::collections::HashSet::new();
    let mut in_roxygen = false;
    let mut prev_was_empty = false;

    for (i, trimmed) in &doc_info {
        if trimmed.starts_with('@') {
            // Start or continue roxygen region
            in_roxygen = true;
            roxygen_indices.insert(*i);
            prev_was_empty = false;
        } else if in_roxygen {
            if trimmed.is_empty() {
                // Empty line in roxygen - might end the block or be part of multi-paragraph tag
                roxygen_indices.insert(*i);
                prev_was_empty = true;
            } else if prev_was_empty {
                // Non-empty line after empty line - end roxygen region
                // This is likely regular documentation
                in_roxygen = false;
                prev_was_empty = false;
            } else {
                // Continuation line (no paragraph break)
                roxygen_indices.insert(*i);
            }
        }
    }

    // Build result excluding roxygen lines
    attrs
        .iter()
        .enumerate()
        .filter(|(i, _)| !roxygen_indices.contains(i))
        .map(|(_, attr)| attr.clone())
        .collect()
}

#[cfg(test)]
mod tests;