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
- Inline the section content into the main description paragraph.
- 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.
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
Run
tinyrox::document().Expected: generated
.Rdcontains a\section{Permissions}{This text should appear in generated Rd.}block.Actual: the section is omitted with no warning. The
.Rdlooks 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_spawnshowed nothing — see cornball-ai/corteza#77 for the fix (inlined the text into the main description as a workaround).Workarounds
## Headingline inside the description (roxygen2-style markdown sections).Suggested resolution
Either render
@sectioninto\section{...}{...}in the generated.Rd, or warn on encountered-but-unsupported roxygen tags so silent drops become loud.