Skip to content

tinyrox drops roxygen @section blocks when generating Rd #10

@TroyHernandez

Description

@TroyHernandez

Summary

tinyrox::document() silently drops @section <Name>: roxygen blocks. The function still generates the rest of the .Rd (description, params, return) but the \section{...}{...} block never appears in the output.

Minimal repro

#' Example function
#'
#' Main description.
#'
#' @section Permissions:
#' This text should appear in generated Rd.
#' @export
f <- function() NULL

Run tinyrox::document().

Expected: generated .Rd contains a \section{Permissions}{This text should appear in generated Rd.} block.

Actual: the section is omitted with no warning. The .Rd looks fine apart from the missing block.

Why it matters

Without a warning, a caller has no signal that their docs are incomplete. We hit this on corteza::subagent_spawn() where a @section Permissions: block documenting the no-mid-run-escalation invariant was silently dropped, so ?subagent_spawn showed nothing — see cornball-ai/corteza#77 for the fix (inlined the text into the main description as a workaround).

Workarounds

  1. Inline the section content into the main description paragraph.
  2. Use a ## Heading line inside the description (roxygen2-style markdown sections).

Suggested resolution

Either render @section into \section{...}{...} in the generated .Rd, or warn on encountered-but-unsupported roxygen tags so silent drops become loud.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions