| Title: | Minimal R Documentation Generator |
| Version: | 0.4.0 |
| Date: | 2026-06-24 |
| Description: | A deterministic, dependency-free documentation generator for R packages. Generates valid Rd files and NAMESPACE from 'roxygen2'-style comments using only base R. Supports a strict subset of tags with no markdown parsing, no inference magic, and explicit-only behavior. |
| License: | GPL-3 |
| URL: | https://github.com/cornball-ai/tinyrox |
| BugReports: | https://github.com/cornball-ai/tinyrox/issues |
| Encoding: | UTF-8 |
| Imports: | utils |
| Suggests: | tinytest |
| NeedsCompilation: | no |
| Packaged: | 2026-06-24 14:50:00 UTC; troy |
| Author: | Troy Hernandez 
[aut, cre],
cornball.ai [cph] |
| Maintainer: | Troy Hernandez <troy@cornball.ai> |
| Repository: | CRAN |
| Date/Publication: | 2026-06-24 15:10:02 UTC |
Known S3 Generic Functions
Description
List of base R S3 generics for auto-detection when @export is used.
Usage
KNOWN_S3_GENERICS
Format
An object of class character of length 139.
Header Marker for tinyrox-Generated Rd Files
Description
The first line of every Rd file tinyrox writes. It both warns against hand editing and lets tinyrox recognise files it owns (see tinyrox_owns_rd()), so document() can prune only its own stale pages.
Usage
RD_MARKER
Format
An object of class character of length 1.
Supported Documentation Tags
Description
Supported Documentation Tags
Usage
SUPPORTED_DOC_TAGS
Format
An object of class character of length 20.
Supported Namespace Tags
Description
Supported Namespace Tags
Usage
SUPPORTED_NS_TAGS
Format
An object of class character of length 6.
All Supported Tags
Description
All Supported Tags
Usage
SUPPORTED_TAGS
Format
An object of class character of length 26.
Collect Assigned Names per Top-Level Expression
Description
A symbol counts as assigned if it is the target of <-, =, or ->, the loop variable of a for(), or a function formal. Used to tell a local variable named T or F apart from the logical shorthand.
Usage
assigned_names(terms)
Arguments
terms |
Terminal tokens sorted by position, with a root column. |
Value
Named list mapping root id to character vector of names.
Reconstruct the Source Text of a Call
Description
Given the SYMBOL_FUNCTION_CALL token id, climbs two levels to the call expression and returns its source text.
Usage
call_expr_text(pd, id, parents)
Arguments
pd |
Full parse data (srcfile attribute required). |
id |
Token id of the SYMBOL_FUNCTION_CALL. |
parents |
Named vector mapping token id to parent id. |
Value
Call source text, or "" if unavailable.
Check R Code for CRAN Issues
Description
Scans R files for common CRAN policy violations. Files are parsed and checked token-wise: comments and string literals are never flagged, print()/cat() are allowed inside print./format. S3 methods, and T/F shorthand is not confused with a local variable named T or F.
Usage
check_code_cran(path = ".")
Arguments
path |
Path to package root directory |
Value
List with issues found
Examples
# Create a minimal package in tempdir
pkg <- file.path(tempdir(), "mypkg")
dir.create(file.path(pkg, "R"), recursive = TRUE, showWarnings = FALSE)
writeLines("Package: mypkg\nTitle: Test\nVersion: 0.1.0",
file.path(pkg, "DESCRIPTION"))
writeLines("add <- function(x, y) x + y",
file.path(pkg, "R", "add.R"))
check_code_cran(pkg)
# Clean up
unlink(pkg, recursive = TRUE)
Check One R File for CRAN Issues
Description
Parses the file and runs the token-level checks. A file that does not parse is reported as a single issue rather than stopping the whole check.
Usage
check_code_file(file)
Arguments
file |
Path to an R source file. |
Value
List of issues (each a list with line and message).
Run Token-Level CRAN Checks on Parse Data
Description
Run Token-Level CRAN Checks on Parse Data
Usage
check_code_tokens(pd)
Arguments
pd |
Parse data from utils::getParseData() with source kept (the srcfile attribute is needed to reconstruct call text). |
Value
List of issues, sorted by line.
Full CRAN Compliance Check
Description
Runs the CRAN compliance checks for package code and examples.
Usage
check_cran(path = ".")
Arguments
path |
Path to package root directory |
Value
List with all issues
Examples
# Create a minimal package in tempdir
pkg <- file.path(tempdir(), "mypkg")
dir.create(file.path(pkg, "R"), recursive = TRUE, showWarnings = FALSE)
writeLines("Package: mypkg\nTitle: Test\nVersion: 0.1.0\nDescription: A test package.",
file.path(pkg, "DESCRIPTION"))
writeLines("add <- function(x, y) x + y",
file.path(pkg, "R", "add.R"))
check_cran(pkg)
# Clean up
unlink(pkg, recursive = TRUE)
Check for Missing Examples
Description
Identifies exported functions that lack examples in their documentation.
Usage
check_examples_cran(path = ".")
Arguments
path |
Path to package root directory |
Value
Character vector of function names missing examples
Examples
# Create a minimal package in tempdir
pkg <- file.path(tempdir(), "mypkg")
dir.create(file.path(pkg, "R"), recursive = TRUE, showWarnings = FALSE)
writeLines("Package: mypkg\nTitle: Test\nVersion: 0.1.0",
file.path(pkg, "DESCRIPTION"))
writeLines("#' Add numbers\n#' @export\nadd <- function(x, y) x + y",
file.path(pkg, "R", "add.R"))
check_examples_cran(pkg)
# Clean up
unlink(pkg, recursive = TRUE)
Clean Generated Files
Description
Removes all Rd files from man/ directory.
Usage
clean(path = ".", namespace = FALSE)
Arguments
path |
Path to package root directory. |
namespace |
Also remove NAMESPACE? Default FALSE. |
Value
No return value, called for side effects.
Examples
# Create a minimal package in tempdir
pkg <- file.path(tempdir(), "mypkg")
dir.create(file.path(pkg, "man"), recursive = TRUE, showWarnings = FALSE)
writeLines("Package: mypkg\nTitle: Test\nVersion: 0.1.0",
file.path(pkg, "DESCRIPTION"))
writeLines("placeholder", file.path(pkg, "man", "test.Rd"))
clean(pkg)
# Clean up
unlink(pkg, recursive = TRUE)
Detect S3 Method from Function Name
Description
Checks if a function name follows the generic.class pattern where generic is a known S3 generic function.
Usage
detect_s3_method(name, pkg_generics = character())
Arguments
name |
Function name to check. |
pkg_generics |
Character vector of S3 generics defined in the package itself, checked in addition to KNOWN_S3_GENERICS. |
Value
List with generic and class components, or NULL if not an S3 method.
Generate Documentation for an R Package
Description
Main function for tinyrox. Parses R source files for documentation comments and generates Rd files and NAMESPACE.
Usage
document(path = ".", namespace = c("overwrite", "append", "none"),
cran_check = TRUE, silent = FALSE, prune_rd = TRUE)
Arguments
path |
Path to package root directory. Default is current directory. |
namespace |
How to handle NAMESPACE generation. One of
|
cran_check |
Run CRAN compliance checks (code issues and missing examples) and undocumented-parameter warnings. Default TRUE. |
silent |
Operate less verbose without messages. Default FALSE. |
prune_rd |
Remove stale Rd files for topics no longer documented (e.g. after a rename or deletion)? Only files tinyrox generated are removed; hand-written Rd is never touched. Default TRUE. Set FALSE to leave existing Rd in place. |
Value
Invisibly returns a list with: - rd_files: character vector of generated Rd file paths - pruned: character vector of stale Rd file paths removed - namespace: path to NAMESPACE file (or NULL if mode="none")
Examples
# Create a minimal package in tempdir
pkg <- file.path(tempdir(), "mypkg")
dir.create(file.path(pkg, "R"), recursive = TRUE, showWarnings = FALSE)
writeLines("Package: mypkg\nTitle: Test\nVersion: 0.1.0",
file.path(pkg, "DESCRIPTION"))
writeLines(c(
"#' Add two numbers",
"#' @param x A number",
"#' @param y A number",
"#' @export",
"add <- function(x, y) x + y"),
file.path(pkg, "R", "add.R"))
# Document the package
document(pkg, cran_check = FALSE)
# Clean up
unlink(pkg, recursive = TRUE)
Escape Special Characters for Rd
Description
Escapes special characters for Rd format, but detects and preserves existing Rd markup (like \describe, \item, \code, etc.).
Usage
escape_rd(text)
Arguments
text |
Text to escape. |
Value
Escaped text.
Extract Function Formals from Code
Description
Extract Function Formals from Code
Usage
extract_formals(code)
Arguments
code |
Code starting with "function(" |
Value
List with 'names' (argument names) and 'usage' (formatted for Rd).
Extract Function Name from Definition Line
Description
Extract Function Name from Definition Line
Usage
extract_function_name(line)
Arguments
line |
Code line potentially containing function definition |
Value
Function name or NULL
Extract Formals from torch nn_module
Description
Extracts the formals from the initialize method of an nn_module definition.
Usage
extract_nn_module_formals(code)
Arguments
code |
Code starting with "nn_module(" or "torch::nn_module(" |
Value
List with 'names' (argument names) and 'usage' (formatted for Rd), or NULL if initialize method not found.
Find Exported Functions Using dontrun in Examples
Description
Parses R file content to find @export tags with \dontrun in @examples.
Usage
find_dontrun_examples(lines)
Arguments
lines |
Character vector of file lines |
Value
Character vector of function names using dontrun
Find Exported Functions Without Examples
Description
Parses R file content to find @export tags without @examples.
Usage
find_exports_without_examples(lines)
Arguments
lines |
Character vector of file lines |
Value
Character vector of function names missing examples
Find Example Lines Exceeding 100 Characters
Description
Scans @examples blocks for lines that will be truncated in the PDF manual.
Usage
find_long_example_lines(lines, filename)
Arguments
lines |
Character vector of file lines |
filename |
Filename for reporting |
Value
Character vector of warnings (file:line format)
Find S3 generics defined in the package
Description
Scans source files for functions that call UseMethod() to identify package-defined S3 generics.
Usage
find_package_generics(blocks)
Arguments
blocks |
Documentation blocks from parse_package(). |
Value
Character vector of generic function names.
Format Object Info for Data Documentation
Description
Generates the format description string for a data object. Tries to load the package namespace to inspect the object.
Usage
format_object_info(name, pkg_path)
Arguments
name |
Object name. |
pkg_path |
Package root path. |
Value
Format string or NULL if object cannot be inspected.
Format Usage Line
Description
Formats the function usage, wrapping to multiple lines if needed. Follows roxygen2 style: each argument on its own line if total > 80 chars. S3 methods use the \method syntax.
Usage
format_usage(name, args, pkg_generics = character())
Arguments
name |
Function name. |
args |
Character vector of arguments with defaults. |
pkg_generics |
Character vector of S3 generics defined in the package itself, used for S3 method detection. |
Value
Formatted usage string.
Generate All Rd Files for a Package
Description
Generate All Rd Files for a Package
Usage
generate_all_rd(blocks, path = ".", cran_check = TRUE)
Arguments
blocks |
List of documentation blocks from parse_package(). |
path |
Package root path. |
cran_check |
Emit CRAN-compliance warnings (undocumented parameters). Default TRUE. |
Value
Character vector of generated file paths.
Generate Rd File Content for Data Objects
Description
Generate Rd File Content for Data Objects
Usage
generate_data_rd(tags, source_file = NULL, format_string = NULL)
Arguments
tags |
Parsed tags from parse_tags(). |
source_file |
Source file path (for header comment). |
format_string |
Format description (e.g., "An object of class list of length 3"). |
Value
Character string of Rd content.
Generate NAMESPACE Content
Description
Generate NAMESPACE Content
Usage
generate_namespace(blocks)
Arguments
blocks |
List of documentation blocks from parse_package(). |
Value
Character string of NAMESPACE content.
Generate Package Documentation Rd
Description
Generates Rd content for package documentation ("_PACKAGE" directive).
Usage
generate_package_rd(tags, pkg_name, source_file)
Arguments
tags |
Parsed tags from the documentation block. |
pkg_name |
Package name. |
source_file |
Source file path. |
Value
Character string of Rd content.
Generate Rd File Content
Description
Generate Rd File Content
Usage
generate_rd(tags, formals = NULL, source_file = NULL, pkg_generics = character())
Arguments
tags |
Parsed tags from parse_tags(). |
formals |
Character vector of formal argument names (for functions). |
source_file |
Source file path (for header comment). |
pkg_generics |
Character vector of S3 generics defined in the package itself, used for S3 method detection in usage lines. |
Value
Character string of Rd content.
Generate Rd Content for Grouped Blocks (Multiple @rdname Entries)
Description
Merges multiple documentation blocks that share an @rdname topic into a single .Rd file. The primary block (whose name matches the topic) provides title/description; all blocks contribute usage/params.
Usage
generate_rd_grouped(topic, entries, all_tags, pkg_generics = character())
Arguments
topic |
Topic name (the @rdname value). |
entries |
List of list(tags, block) pairs sharing this topic. |
all_tags |
All parsed tags (for @inheritParams resolution). |
pkg_generics |
Character vector of S3 generics defined in the package itself, used for S3 method detection in usage lines. |
Value
Character string of merged Rd content.
Get Package Name from DESCRIPTION
Description
Get Package Name from DESCRIPTION
Usage
get_package_name(path)
Arguments
path |
Package root path. |
Value
Package name.
Parse R Files for Documentation Blocks
Description
Extracts documentation comment blocks and their associated objects from R source files.
Usage
parse_file(file)
Arguments
file |
Path to an R source file. |
Value
A list of documentation blocks, each with components: - lines: character vector of comment lines (without #') - object: name of the documented object - type: "function", "data", or "other" - formals: for functions, the formal arguments
Parse Formals Text
Description
Parse Formals Text
Usage
parse_formals_text(text)
Arguments
text |
Text containing function arguments. |
Value
List with 'names' (argument names) and 'usage' (formatted for Rd).
Parse Object Definition
Description
Identifies the object being defined from code text (may be multi-line).
Usage
parse_object_definition(text, file, line_num)
Arguments
text |
The code text (may span multiple lines). |
file |
The source file (for error messages). |
line_num |
The line number (for error messages). |
Value
A list with name, type, and formals, or NULL if not a definition.
Parse All R Files in a Package
Description
Parse All R Files in a Package
Usage
parse_package(path = ".")
Arguments
path |
Path to package root. |
Value
List of all documentation blocks from all R files.
Parse Tags from Documentation Lines
Description
Parse Tags from Documentation Lines
Usage
parse_tags(lines, object_name, file = NULL, line_num = NULL)
Arguments
lines |
Character vector of documentation lines (without #'). |
object_name |
Name of the documented object. |
file |
Source file (for error messages). |
line_num |
Starting line number (for error messages). |
Value
A list with parsed tag values.
Examples
lines <- c("Title Here", "", "Description text.", "", "@param x A number.",
"@return The number.", "@export")
tags <- parse_tags(lines, "my_function")
tags$title
tags$params
Prune Stale tinyrox-Generated Rd Files
Description
Removes man/*.Rd files that the current document() run did not (re)generate, but only those tinyrox can prove it owns via tinyrox_owns_rd(). Hand-written Rd, and any Rd lacking the marker, are left untouched.
Usage
prune_stale_rd(path, generated, silent = FALSE)
Arguments
path |
Package root directory. |
generated |
Character vector of Rd file paths produced this run. |
silent |
Suppress the removal message? Default FALSE. |
Value
Character vector of removed file paths (invisibly).
Render User-Defined @section Blocks to Rd
Description
Emits one Rd section macro per parsed @section tag. Content is passed through verbatim as Rd (tinyrox does no markdown parsing), matching how the title-only macros elsewhere treat hand-written Rd markup.
Usage
render_sections(sections)
Arguments
sections |
List of 'list(title=, content=)' from parse_tags(). |
Value
Character vector of Rd lines (empty when there are no sections).
Resolve Parameters from External Package Rd Files
Description
Reads an installed package's Rd file to extract parameter documentation for use with '@inheritParams pkg::function'.
Usage
resolve_external_params(source_name)
Arguments
source_name |
Character string like "base::cat" or "stats::lm". |
Value
Named list of parameter descriptions, or empty list on failure.
Resolve @inheritParams Tags
Description
Copies parameter documentation from source functions to the current function. Only inherits params that are: (1) in the current function's formals, and (2) not already documented in the current function.
Usage
resolve_inherit_params(tags, all_tags, formals)
Arguments
tags |
Current function's parsed tags. |
all_tags |
Named list of all parsed tags (name -> tags). |
formals |
Current function's formals (list with names and usage). |
Value
Updated tags with inherited params merged in.
Name of the Function a Top-Level Expression Defines
Description
Recognizes the pattern name <- function(...) (also = and quoted or backticked names). Anything else returns NA.
Usage
root_function_name(root_id, terms)
Arguments
root_id |
Top-level expression id. |
terms |
Terminal tokens sorted by position, with a root column. |
Value
Function name as a string, or NA.
Save a Parsed Tag Value
Description
Save a Parsed Tag Value
Usage
save_tag(result, tag, arg, accumulator, file, line_num)
Arguments
result |
Current result list to update. |
tag |
Tag name (e.g., "param", "return"). |
arg |
First-line argument after the tag. |
accumulator |
Continuation lines for the tag. |
file |
Source file path (for error messages). |
line_num |
Line number (for error messages). |
Identify a tinyrox-Generated Rd File
Description
Returns TRUE only if the file's first line is exactly RD_MARKER. This is deliberately conservative: hand-written Rd, or Rd written by other tools, never matches, so prune_stale_rd() cannot delete them.
Usage
tinyrox_owns_rd(file)
Arguments
file |
Path to an Rd file. |
Value
TRUE if tinyrox generated the file, FALSE otherwise.
Find the Top-Level Expression Containing a Token
Description
Find the Top-Level Expression Containing a Token
Usage
token_root(id, parents)
Arguments
id |
Token id from parse data. |
parents |
Named vector mapping token id to parent id. |
Value
Id of the top-level expression.
Warn About Dropped NAMESPACE Directives
Description
Compares the existing NAMESPACE against newly generated content and warns about directives the regeneration drops. export() and S3method() lines are excluded - those legitimately churn as tags change. Anything else that vanishes (a hand-added useDynLib(), an import() with no backing tag) is load-bearing and the silent drop breaks packages at runtime.
Usage
warn_dropped_directives(filepath, content)
Arguments
filepath |
Path to the existing NAMESPACE file. |
content |
Newly generated NAMESPACE content string. |
Wrap Text to Width
Description
Wraps text to specified width, preserving words.
Usage
wrap_text(text, width = 72)
Arguments
text |
Text to wrap. |
width |
Maximum line width. |
Value
Wrapped text with newlines.
Write NAMESPACE File
Description
Write NAMESPACE File
Usage
write_namespace(content, path = ".", mode = "overwrite")
Arguments
content |
NAMESPACE content string. |
path |
Package root path. |
mode |
Either "overwrite" or "append". |
Write Rd File
Description
Write Rd File
Usage
write_rd(content, name, path = ".")
Arguments
content |
Rd content string. |
name |
Topic name. |
path |
Package root path. |