11 Generating R documentation
When your code uses offensive programming features, it becomes much easier to generate R documentation, as now, several information might be deduced and reused for manual pages composition. Let’s see how.
11.1 Automated R documentation generation
Using package wyz.code.rdoc, manual pages .Rd files stored in man folder in a package context can be automatically created and filled up nearly to completion, depending on the level of offensive programming instrumentation of your code.
Generated manual pages uses English language. Feel free to modify produced English, to match your own English flavor, if needed.
The level of your R code instrumentation will impact the quality of the generation and your review work depth and time. When using both function return type instrumentation and test case instrumentation, expects produced manual page content to be fully generated and ready for review.
No automated generation of manual page is possible when your code is not offensive programming instrumented. In such a case, rely either on standard R tools to generate documentation or use package wyz.code.rdoc to create the artifact program that will reduce the burden of documentation generation.
11.2 Focus on R documentation generation
Package wyz.code.rdoc generates manual page sections, presented below with their information source and your remaining duties.
| R manual section | information source | your duty |
|---|---|---|
| name | R code | none |
| alias | R code | none, unless you want to add extraneous aliases |
| title | R code | none |
| usage | R code | none |
| arguments | R code | none |
| value | R code | none if your code is function return type instrumented. Otherwise, you will have to write explicitly this part. |
| details | R code | you may complete this part that is generated when your code is function test case instrumented. |
| references | your instruction | Generated from instructions you may provide. |
| author | package DESCRIPTION | none |
| seealso | your instruction | Generated from instructions you may provide. |
| keyword | your instruction | Generated from instructions you may provide. |
| examples | R code | none when your code is function test case instrumented. |
| concept | your instruction | Generated from instructions you may provide. |
Missing sections can be added on your instruction when generating manual pages. Package wyz.code.rdoc provides a convenient and easy way to do so.
The generated manual page can be used as-is, and should be immediately viewable and usable. From a format point of view, it complies with .Rd file syntax. From a content point of view, generated content aims to be reliable and express in human readable English wherever this makes sense. Indeed, you may bring desired enhancements to generated English sentences as you want.
Generated manual page requires review. You may add extraneous content, modify provided content and beautify the result. See known limits section 9.3 to know more.
11.3 package wyz.code.rdoc utilities
The package wyz.code.rdoc can be used to produce R documentation parts and R documentation generation programs.
Here under are presented a few utilities that will greatly help you in producing high quality manual pages. Please, take time to read the full paragraph as it will mind you about some very convenient R functions to produces R code documentation snippets. For more information, refer to respective manual pages.
11.3.1 Generate a R documentation section
Use function generateSection to generate a standard manual page section. Provide section name as first argument, and content as second.
library(wyz.code.rdoc)
print(generateSection('note', 'A note text.'))
#> [1] "\\note{\nA note text.\n}"This function does not allow you to generate a customized non standard manual page section. To do so, use generateContent.
11.3.2 Format an English sentence
Use function sentensize to format a sentence.
This functions ensures sentence starts with an upper-cased letter, adds a final dot if missing, and normalizes spaces, to ease readability.
11.3.3 Generate some R documentation content
Use function generateContent to generate some R documentation content. Beware, as argument order is opposite to the one used for generateSection.
print(generateContent('a title', 'title'))
#> [1] "\\title{a title}"
print(generateContent('https://neonira.github.io/offensiveProgrammingBook/', 'href',
'Offensive Programming Book'))
#> [1] "\\href{https://neonira.github.io/offensiveProgrammingBook/}{Offensive Programming Book}"
print(generateContent('warning', 'section', 'Warning section content ...'))
#> [1] "\\section{warning}{\nWarning section content ...\n}"
print(generateContent('a', 'item', 'description of a', useSpace_b_1 = TRUE))
#> [1] "\\item{a} {description of a}"
print(generateContent('a', 'item', 'description of a', useSpace_b_1 = FALSE))
#> [1] "\\item{a}{description of a}"11.3.4 Generate cross-ref to other R package
Use function generateSpecialLink to generate a R documentation cross-ref to any other R package.
11.4 Manual pages generation
Simply use generateDocumentationContent to do so.
11.4.1 Context setup
I will reuse some classes delivered with wyz.code.offensiveProgramming to ease demonstration of R documentation generation.
target_folder <- 'man' #"~/tmp/generated-doc"
if (!dir.exists(target_folder)) dir.create(target_folder)
source_package <- 'wyz.code.offensiveProgramming'
source_files <- c(
'code-samples/both-defs/good/full/AdditionTCFIG1.R',
'code-samples/no-defs/Addition.R',
'code-samples/frt-defs/good/partial/AdditionFIPartial.R',
'code-samples/tcd-defs/good/partial/AdditionTCPartial.R'
)
invisible(sapply(source_files, function(e) {
source(system.file(e, package = source_package))
}))11.4.2 Method manual page
Use keyword method to generate a dedicated manual page for an S3 method.
object <- AdditionTCFIG1()
package_name <- 'zorg'
refs <- list(
list(url = 'https://cran.r-project.org/doc/manuals/R-exts.html',
label = 'Writing R extensions',
comment = 'to know more about R documentation requirements'),
list(url = 'https://www.burns-stat.com/pages/Tutor/R_inferno.pdf',
label = 'The R Inferno',
comment = 'to discover some well-known R weirdness')
)
extra_method <- list(
keyword = c('classes', 'environment', 'utilities', 'misc'),
concept = c('evaluation mode', 'standard evaluation',
'function return type evaluation', 'parameter check evaluation'),
references = c(sentensize(paste('see',
generateContent('wyz.code.offensiveProgramming', 'code'),
'package documentation')),
'',
sentensize(paste('You may read',
generateContent('https://neonira.github.io/offensiveProgrammingBook/',
'href', 'Offensive Programming Book'),
'to get introduction and expert advices on offensive programming')),
'',
generateReference(refs[[1]])
),
seealso = c(sentensize(paste('see',
generateContent(generateSpecialLink('wyz.code.offensiveProgramming',
'runTransientFunction'),
'code'),
'to call interactively an offensive programming function, whether instrumented or not.')),
'',
sentensize(paste('see',
generateContent(generateSpecialLink('wyz.code.offensiveProgramming',
'runTestCase'),
'code'),
'to reuse on-demand instrumented offensive programming function tests'))
)
)
# explicit invocation for method
generateDocumentationContent(target_folder, 'method', 'addMultiDouble',
object, package_name,
extra_method, overwrite_b_1 = TRUE)Note how parameter extra_method allows you to provide specific content as instruction to be considered for manual page generation. The extraneous content must be a list, where names are manual page sections, and where content is R documentation content.
You may use function generateDocumentationContent to generate your own R documentation generation scripts. This allows you to generate programmatically your manual pages, in a customized way.
Note that parameter package_name is the name of the target package you want to generate documentation for. Here, files are taken from the wyz.code.offensiveProgramming package, and documentation is generated for package zorg. Really useful when programming, not so useful when used interactively.
11.4.3 Class manual page
Use keyword class to create a manual page for a class. Provide the class name.
11.4.4 Package manual page
Use keyword class to generate a summary manual page for your package. Provide explicitly, all the class names you desired to emphase over.
extra_package <- extra_method
extra_package$seealso <- NULL
extra_package$content <- c('AdditionTCFIG1', 'AdditionTCFIP', 'Addition')
z <- generateDocumentationContent(target_folder, 'package', package_name,
object, package_name, extra_package, overwrite_b_1 = TRUE)
\name{zorg-package}
\alias{zorg-package}
\alias{zorg}
\docType{package}
\title{\packageTitle{zorg}}
\description{
\packageDescription{zorg}
}
\details{
Most important package entries are
\itemize{
\item{\code{\link{AdditionTCFIG1}}}{}
\item{\code{\link{AdditionTCFIP}}}{}
\item{\code{\link{Addition}}}{}
}
}
\references{
See \code{wyz.code.offensiveProgramming} package documentation.
You may read \href{https://neonira.github.io/offensiveProgrammingBook/}{Offensive Programming Book} to get introduction and expert advices on offensive programming.
Refer to \href{https://cran.r-project.org/doc/manuals/R-exts.html}{Writing R extensions} to know more about R documentation requirements.
}
\author{
\packageAuthor{zorg}
Maintainer: \packageMaintainer{zorg}
}
\keyword{classes}
\keyword{environment}
\keyword{utilities}
\keyword{misc}
\concept{evaluation mode}
\concept{standard evaluation}
\concept{function return type evaluation}
\concept{parameter check evaluation}
11.4.5 In one shot
To simplify your life, you can create in one shot all the manual pages related to methods of a class. Simply pass NA as value for the name.
generateDocumentationContent(target_folder, 'method', NA,
AdditionTCPartial(), package_name,
extra_method, overwrite_b_1 = TRUE)
#> $addDouble
#> $addDouble$filename
#> [1] "man/addDouble.AdditionTCPartial.Rd"
#>
#> $addDouble$overwritten
#> [1] TRUE
#>
#>
#> $addInteger
#> $addInteger$filename
#> [1] "man/addInteger.AdditionTCPartial.Rd"
#>
#> $addInteger$overwritten
#> [1] TRUE
#>
#>
#> $addNumeric
#> $addNumeric$filename
#> [1] "man/addNumeric.AdditionTCPartial.Rd"
#>
#> $addNumeric$overwritten
#> [1] TRUE
#>
#>
#> $divideByZero
#> $divideByZero$filename
#> [1] "man/divideByZero.AdditionTCPartial.Rd"
#>
#> $divideByZero$overwritten
#> [1] TRUE
#>
#>
#> $generateError
#> $generateError$filename
#> [1] "man/generateError.AdditionTCPartial.Rd"
#>
#> $generateError$overwritten
#> [1] TRUE
#>
#>
#> $generateWarning
#> $generateWarning$filename
#> [1] "man/generateWarning.AdditionTCPartial.Rd"
#>
#> $generateWarning$overwritten
#> [1] TRUE11.4.6 and a special case, from a standalone function
When you own an offensive programming instrumented function, it is quite easy to get a pre-filled R documentation file from it. Be sure to pass NULL as value for parameter object_o_1.
sumValues <- function(x_i, y_i) sum(x_i, y_i, na.rm = TRUE)
gmf <- generateDocumentationContent(target_folder, 'method', 'sumValues',
NULL, package_name,
extra_method, overwrite_b_1 = TRUE)
print(gmf)
#> $filename
#> [1] "man/sumValues.Rd"
#>
#> $overwritten
#> [1] TRUEIndeed, this convenience suffers from two drawbacks
- As the return type of the function is unknown, value section cannot be documented,
- As they are no test case definitions, examples section cannot be documented
11.5 Known-limits
Generation of manual pages can be quite tricky. Whereas package wyz.code.rdoc alleviates greatly the burden, some pitfalls remain. Here they are
- Generated manual page might not respect the maximum line length required by R CMD check, and this tool will provide explicit information about un-compliance. To solve issue, just split the content by adding carriage return wherever required.
- Generated documentation is quite stereotyped. Inject your instruction to customize the result.
11.6 Opportunities
Reuse can be made at several levels depending of your needs. Roughly speeking, you maty aim for one of these 3 levels of customization 1. just customize some textual information. Generate the pages using package wyz.code.rdoc and modify page contents manually is generally the best way to achieve this goal 1. customize some manual pages sections. Generate the pages using package wyz.code.rdoc while providing some dedicated context information. Refer to previous examples, and look at variables starting with extra_. They allow you to inject your customized content in targeted sections. 1. If you seek for fully customized manual page generation, then you may use package (ref:rd) to create your own R generation scheme. That way you will get the benefit of starting launched, using high-level R documentation generation functions, and also get the ability to reuse and customized provided generation scheme. This package uses only R code, and so you could get insight and reuse any part of it.