From 1e5971a5f9aeeab4e1aa736542941b6047de8306 Mon Sep 17 00:00:00 2001 From: raiyyan Date: Wed, 8 Oct 2025 18:29:40 +0530 Subject: [PATCH] Update documenting.qmd with tools::checkRd section Adds a new section on checking Rd files using tools::checkRd to documenting.qmd. - Provides practical usage examples, explanations of typical errors caught, and instructions for using the function - Includes code blocks for R syntax highlighting and output samples - Improves clarity for contributors on how to validate Rd documentation before package submission - Addresses issue #164 and follows best practices for documentation maintenance This change helps maintain documentation quality and makes it easier for others to understand and apply Rd file validation. --- chapters/documenting.qmd | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/chapters/documenting.qmd b/chapters/documenting.qmd index 8bf5c88..e9bf700 100644 --- a/chapters/documenting.qmd +++ b/chapters/documenting.qmd @@ -101,6 +101,36 @@ All the above information is included in a `.Rd` file within a series of section * Use `--` for page ranges. * For giving an address for a publisher use the format `New York: Springer-Verlag`. +## Checking Rd Files with tools::checkRd + +tools::checkRd is a utility function in R for checking the validity and consistency of Rd (R documentation) files. It helps catch common formatting errors, such as missing brackets and non-ASCII characters, by performing a number of sanity checks on the file. + +# Usage + +```r +tools::checkRd("path/to/file.Rd") ``` + +# What It Checks + +* Missing or mismatched brackets { } +* Non-ASCII characters (when encoding is not declared) +* Presence of required documentation sections +* Section names and valid tag usage +* Non-empty braces and unnecessary braces +* Table formatting and section duplication issues + +# Notes + +Use this function when editing Rd files to ensure documentation quality and avoid CRAN submission errors. + +Always declare encoding if your documentation includes non-ASCII characters. + +# Reference + +Official documentation: https://cran.r-project.org/web/packages/tools/refman/tools.html + +Community example: https://rdrr.io/r/tools/checkRd.html + For example, the help file for `base::mean()` is found at . The file`mean.Rd` has the content shown below: ```