| Title: | Wizardry Code Offensive Programming R Documentation |
|---|---|
| Description: | Allows to generate on-demand or by batch, any R documentation file, whatever is kind, data, function, class or package. It populates documentation sections, either automatically or by considering your input. Input code could be standard R code or offensive programming code. Documentation content completeness depends on the type of code you use. With offensive programming code, expect generated documentation to be fully completed, from a format and content point of view. With some standard R code, you will have to activate post processing to fill-in any section that requires complements. Produced manual page validity is automatically tested against R documentation compliance rules. Documentation language proficiency, wording style, and phrasal adjustments remains your job. |
| Authors: | Fabien Gelineau <[email protected]> |
| Maintainer: | Fabien Gelineau <[email protected]> |
| License: | GPL-3 |
| Version: | 1.1.19 |
| Built: | 2026-05-17 09:54:23 UTC |
| Source: | https://github.com/cran/wyz.code.rdoc |
Audit documentation files from a set of folders
auditDocumentationFiles(folder_s_1m)auditDocumentationFiles(folder_s_1m)
folder_s_1m |
An length-1 or more |
Provides a named list with two entries named correct and
incorrect. All entries are file names.
Incorrect entries are the ones that has length issues as detected by function
computeDocumentationStatistics.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Function verifyDocumentationFile allows to check documentation content
using standard R function tools:checkRd.
auditDocumentationFiles('man')auditDocumentationFiles('man')
R documentation beautifying functions
beautify(escapeBraces_b_1 = FALSE)beautify(escapeBraces_b_1 = FALSE)
escapeBraces_b_1 |
A single |
A named list of R vectorized functions. See examples below.
Content provided to function will be processed by function
generateMarkup.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
b <- beautify() cat('length', length(b), '\n') #25 cat(names(b), '\n') # acronym bold cite code dQuote email emph enc env figure file format kbd link # option pkg preformatted samp source sQuote strong url var verb codelink x <- 'some content' cat(x, ':', b$code(x), '\n') #some content : \code{some content}b <- beautify() cat('length', length(b), '\n') #25 cat(names(b), '\n') # acronym bold cite code dQuote email emph enc env figure file format kbd link # option pkg preformatted samp source sQuote strong url var verb codelink x <- 'some content' cat(x, ':', b$code(x), '\n') #some content : \code{some content}
Complete a manual page
completeManualPage(filename_s_1, processingContext_o, add_b_1 = TRUE, verbosity_b_1 = FALSE)completeManualPage(filename_s_1, processingContext_o, add_b_1 = TRUE, verbosity_b_1 = FALSE)
filename_s_1 |
A single |
processingContext_o |
a single processing |
add_b_1 |
a |
verbosity_b_1 |
a single |
This function adds or patches on-demand sections of a manual page file.
You may consider twice prior using this function. It is a convenience that aims
to sustain your productivity. You may get very quick results using it, but at the
probable cost of non reproducibility in comparison with manual pages produced using
function ManualPageBuilder.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
f <- function() {} ic <- InputContext(NULL, 'f') p <- produceManualPage(ic) # WARNING: File /tmp/Rtmpvk4BG5/f.Rd # checkRd: (5) /tmp/Rtmpvk4BG5/f.Rd:0-9: Must have a \description completeManualPage(p$context$filename, ProcessingContext(postProcessing_l = list( details = function(content_s) 'some more details', concept = function(content_s) 'yet another concept' )), verbosity = TRUE ) # adding details # adding concept # [1] TRUEf <- function() {} ic <- InputContext(NULL, 'f') p <- produceManualPage(ic) # WARNING: File /tmp/Rtmpvk4BG5/f.Rd # checkRd: (5) /tmp/Rtmpvk4BG5/f.Rd:0-9: Must have a \description completeManualPage(p$context$filename, ProcessingContext(postProcessing_l = list( details = function(content_s) 'some more details', concept = function(content_s) 'yet another concept' )), verbosity = TRUE ) # adding details # adding concept # [1] TRUE
Compute documentation statistics, providing section length in lines and identifying too long lines.
computeDocumentationStatistics(filename_s_1, maxLineLength_pi_1 = 100L)computeDocumentationStatistics(filename_s_1, maxLineLength_pi_1 = 100L)
filename_s_1 |
A single |
maxLineLength_pi_1 |
A single positive |
Wherever a line_length_issue is not NA, you should correct the
faulty line by editing the file. Not doing so will very probably imply a failure
during check package procedure execution.
A data.table with three columns.
keywords |
the section names embedded in the file |
lines |
the number of lines for the section |
line_length_issue |
the line numbers where issues are found or |
This function should be use when prior package delivery, to ensure documentation lines meet the R documentation specifications.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
# computeDocumentationStatistics('myfile.Rd')# computeDocumentationStatistics('myfile.Rd')
Generate example section content from R code.
convertExamples(examples_l, captureOutput_b_1n = TRUE, mode_s_1n = c(NA, "donttest", "dontrun", "dontshow")[1])convertExamples(examples_l, captureOutput_b_1n = TRUE, mode_s_1n = c(NA, "donttest", "dontrun", "dontshow")[1])
examples_l |
An unconstrained |
captureOutput_b_1n |
a length-1 or N |
mode_s_1n |
An length-1 or N vector of |
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
someComputation <- function(numberAsString_s_1) { suppressWarnings(sum(as.integer(strsplit(numberAsString_s_1, '')[[1]]), na.rm = TRUE)) } examples <- list( function() { someComputation("145") }, function() { someComputation("1547215") }, function() { someComputation(NA_character_) }, function() { invisible(someComputation("0x145ABC")) } ) cat(convertExamples(examples, TRUE , c(NA_character_, 'donttest', 'dontrun', 'dontshow'))) # ------- example 1 ------- # someComputation("145") # 10 # \\donttest{ # ------- example 2 ------- someComputation("1547215") # 25 # } # \\dontrun{ # ------- example 3 ------- # someComputation(NA) # 0 # } # \dontshow{ # ------- example 4 ------- #invisible(someComputation("0x145ABC")) # }"someComputation <- function(numberAsString_s_1) { suppressWarnings(sum(as.integer(strsplit(numberAsString_s_1, '')[[1]]), na.rm = TRUE)) } examples <- list( function() { someComputation("145") }, function() { someComputation("1547215") }, function() { someComputation(NA_character_) }, function() { invisible(someComputation("0x145ABC")) } ) cat(convertExamples(examples, TRUE , c(NA_character_, 'donttest', 'dontrun', 'dontshow'))) # ------- example 1 ------- # someComputation("145") # 10 # \\donttest{ # ------- example 2 ------- someComputation("1547215") # 25 # } # \\dontrun{ # ------- example 3 ------- # someComputation(NA) # 0 # } # \dontshow{ # ------- example 4 ------- #invisible(someComputation("0x145ABC")) # }"
Data set to be used as example for demo purpose.
dummydummy
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Data set generated by NEONIRA
Manage characters to be escaped in R documentation text
escapeContent(content_s_1, escapeBraces_b_1 = FALSE)escapeContent(content_s_1, escapeBraces_b_1 = FALSE)
content_s_1 |
A single |
escapeBraces_b_1 |
A single |
A single string with character '@' and '%' escaped.
When escapeBraces_b_1 is set, characters '{' and '}' are also escaped.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
escapeContent('[email protected]') # "www@@xxx.com" escapeContent('\\code{ x %% y }', TRUE) # "\\code\{ x \%\% y \}"escapeContent('[email protected]') # "www@@xxx.com" escapeContent('\\code{ x %% y }', TRUE) # "\\code\{ x \%\% y \}"
Data set to be used as example for demo purpose.
familyfamily
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Data set generated by NEONIRA
Generate special markup for encoding text in R documentation
generateEnc(entries_l)generateEnc(entries_l)
entries_l |
An unconstrained named |
A list of strings
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
generateEnc(list(list(text = 'Français', ascii = 'Francais'))) # [[1]] # [1] "\enc{Français}{Francais}" generateEnc(list(list(text = 'é', ascii = 'e'), list(text = 'è', ascii = 'e'))) # [[1]] # [1] "\enc{é}{e}" # [[2]] # [1] "\enc{è}{e}"generateEnc(list(list(text = 'Français', ascii = 'Francais'))) # [[1]] # [1] "\enc{Français}{Francais}" generateEnc(list(list(text = 'é', ascii = 'e'), list(text = 'è', ascii = 'e'))) # [[1]] # [1] "\enc{é}{e}" # [[2]] # [1] "\enc{è}{e}"
Generate enumeration for R documentation
generateEnumeration(entries_s, itemize_b_1 = FALSE)generateEnumeration(entries_s, itemize_b_1 = FALSE)
entries_s |
An unconstrained vector of |
itemize_b_1 |
A single |
A special character vector to mimic either enumerate or
itemize accordingly to R documentation specification.
Set itemize_b_1 to TRUE if you want an item list,
instead of an enumeration.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
generateEnumeration(LETTERS[1:3]) # [1] "\enumerate{\item A\n\item B\n\item C}" generateEnumeration(LETTERS[1:3], TRUE) # [1] "\itemize{\item A\n\item B\n\item C}"generateEnumeration(LETTERS[1:3]) # [1] "\enumerate{\item A\n\item B\n\item C}" generateEnumeration(LETTERS[1:3], TRUE) # [1] "\itemize{\item A\n\item B\n\item C}"
Generate R documentation atomic pieces, managing various parameters to fulfil R documentation requirements.
generateMarkup(content_s, keyword_s_1 = NA_character_, content2_s = NA_character_, inline_b_1 = TRUE, useSpace_b_1 = FALSE, escapeBraces_b_1 = FALSE, content3_s = NA_character_)generateMarkup(content_s, keyword_s_1 = NA_character_, content2_s = NA_character_, inline_b_1 = TRUE, useSpace_b_1 = FALSE, escapeBraces_b_1 = FALSE, content3_s = NA_character_)
content_s |
a |
keyword_s_1 |
a R documentation keyword. See
|
content2_s |
a |
inline_b_1 |
a single |
useSpace_b_1 |
a single |
escapeBraces_b_1 |
when |
content3_s |
a |
Very convenient function, to customize your R documentation output.
Might be used programmatically to generate pieces or full documentation.
Tested thoroughly with zero, one, two and three contents to cover all the markups of R documentation.
See examples below.
A single string, containing one or several lines of text.
Provided content is processed by function escapeContent.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Refer to Writing R extensions to know more about R documentation requirements.
Refer to escapeContent.
# 0. zero content example print(generateMarkup(keyword = 'R')) # "\\R" # 1. one content example print(generateMarkup('a title', 'title')) # "\\title{a title}" # 2. Two contents examples print(generateMarkup('https://neonira.github.io/offensiveProgrammingBook/', 'href', 'Offensive Programming Book')) # "\\href{https://neonira.github.io/offensiveProgrammingBook/}{Offensive Programming Book}" print(generateMarkup('a', 'item', 'description of a', useSpace_b_1 = TRUE)) # "\\item{a} {description of a}" print(generateMarkup('a', 'item', 'description of a', useSpace_b_1 = FALSE)) "\\item{a}{description of a}" # 3. Three contents example print(generateMarkup('content_1', 'ifelse', 'content_2', content3_s = 'content_3')) # "\\ifelse{content_1}{content_2}{content_3}"# 0. zero content example print(generateMarkup(keyword = 'R')) # "\\R" # 1. one content example print(generateMarkup('a title', 'title')) # "\\title{a title}" # 2. Two contents examples print(generateMarkup('https://neonira.github.io/offensiveProgrammingBook/', 'href', 'Offensive Programming Book')) # "\\href{https://neonira.github.io/offensiveProgrammingBook/}{Offensive Programming Book}" print(generateMarkup('a', 'item', 'description of a', useSpace_b_1 = TRUE)) # "\\item{a} {description of a}" print(generateMarkup('a', 'item', 'description of a', useSpace_b_1 = FALSE)) "\\item{a}{description of a}" # 3. Three contents example print(generateMarkup('content_1', 'ifelse', 'content_2', content3_s = 'content_3')) # "\\ifelse{content_1}{content_2}{content_3}"
Generate cross reference in R documentation
generateOptionLink(options_s_1, topicName_s_1, escapeBraces_b_1 = FALSE)generateOptionLink(options_s_1, topicName_s_1, escapeBraces_b_1 = FALSE)
options_s_1 |
A single |
topicName_s_1 |
A single |
escapeBraces_b_1 |
A single |
A single string, containing one option link. See references and examples below.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Refer to Writing R extensions section 2.5, to know more about using cross references in R documentation.
# Typical use case generateOptionLink('myPackage', 'myFunction') #[1] "\\link[myPackage]{myFunction}" # Refer to reference R documentation for following case generateOptionLink('=terms.object', 'terms') #[1] "\\link[=terms.object]{terms}"# Typical use case generateOptionLink('myPackage', 'myFunction') #[1] "\\link[myPackage]{myFunction}" # Refer to reference R documentation for following case generateOptionLink('=terms.object', 'terms') #[1] "\\link[=terms.object]{terms}"
Generation option Sexpr in R documentation
generateOptionSexpr(options_s_1, topicName_s_1, escapeBraces_b_1 = FALSE)generateOptionSexpr(options_s_1, topicName_s_1, escapeBraces_b_1 = FALSE)
options_s_1 |
A single |
topicName_s_1 |
A single |
escapeBraces_b_1 |
A single |
A single string, containing one option Sexpr. See references and examples below.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Refer to
Writing R extensions
section 2.12, to know more about using Sexpr handling in R documentation.
generateOptionSexpr('echo=TRUE', 'x <- 1') #[1] "\\Sexpr[echo=TRUE]{x <- 1}"generateOptionSexpr('echo=TRUE', 'x <- 1') #[1] "\\Sexpr[echo=TRUE]{x <- 1}"
Generate paragraph, collating provided contents with given string.
generateParagraph(..., collapse_s_1 = "\n", addFinalSeparator_b_1 = FALSE)generateParagraph(..., collapse_s_1 = "\n", addFinalSeparator_b_1 = FALSE)
... |
additional arguments, content to be collated. |
collapse_s_1 |
The |
addFinalSeparator_b_1 |
A single |
A single string, with possibly many new line character embedded.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Functions generateParagraph2NL and
generateParagraphCR.
generateParagraph(LETTERS[1:3]) # "A\nB\nC" generateParagraph(LETTERS[1:3], addFinalSeparator_b_1 = TRUE) # "A\nB\nC\n"generateParagraph(LETTERS[1:3]) # "A\nB\nC" generateParagraph(LETTERS[1:3], addFinalSeparator_b_1 = TRUE) # "A\nB\nC\n"
Generate paragraph, collating provided contents with double new line.
generateParagraph2NL(..., addFinalSeparator_b_1 = FALSE)generateParagraph2NL(..., addFinalSeparator_b_1 = FALSE)
... |
additional arguments. |
addFinalSeparator_b_1 |
A single |
A single string, with possibly many new line character embedded.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Functions generateParagraph and
generateParagraphCR.
generateParagraph2NL(LETTERS[1:3]) # "A\n\nB\n\nC" generateParagraph2NL(LETTERS[1:3], addFinalSeparator_b_1 = TRUE) # "A\n\nB\n\nC\n\n"generateParagraph2NL(LETTERS[1:3]) # "A\n\nB\n\nC" generateParagraph2NL(LETTERS[1:3], addFinalSeparator_b_1 = TRUE) # "A\n\nB\n\nC\n\n"
Data set to be used as example for demo purpose.
generateParagraphCR(..., addFinalSeparator_b_1 = FALSE)generateParagraphCR(..., addFinalSeparator_b_1 = FALSE)
... |
additional arguments. |
addFinalSeparator_b_1 |
A single |
A single string, with possibly many embedded '\cr' character sequences.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Data set generated by NEONIRA
Functions generateParagraph and
generateParagraph2NL.
generateParagraphCR(LETTERS[1:3]) # "A\\crB\\crC" generateParagraphCR(LETTERS[1:3], addFinalSeparator_b_1 = TRUE) # "A\\crB\\crC\cr"generateParagraphCR(LETTERS[1:3]) # "A\\crB\\crC" generateParagraphCR(LETTERS[1:3], addFinalSeparator_b_1 = TRUE) # "A\\crB\\crC\cr"
Generate text to standardize references.
generateReference(data_l)generateReference(data_l)
data_l |
An unconstrained |
A single string, containing the generated reference text. Can be appended several
times to elaborate a multiple reference text.
See references and examples below.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Refer to Writing R extensions to know more about using web references in R documentation.
generateReference( list(url = 'https://neonira.github.io/offensiveProgrammingBook/', label = 'Offensive Programming Book') ) # "Refer to # \\href{https://neonira.github.io/offensiveProgrammingBook/}{Offensive Programming Book}."generateReference( list(url = 'https://neonira.github.io/offensiveProgrammingBook/', label = 'Offensive Programming Book') ) # "Refer to # \\href{https://neonira.github.io/offensiveProgrammingBook/}{Offensive Programming Book}."
Function to create easily function signature from an S3 class
generateS3MethodSignature(methodName_s_1, className_s_1, argumentNames_s)generateS3MethodSignature(methodName_s_1, className_s_1, argumentNames_s)
methodName_s_1 |
a single |
className_s_1 |
a single |
argumentNames_s |
a |
A single string.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Refer to Writing R extensions to know more about R documentation requirements.
print(generateReference( list(url = 'https://neonira.github.io/offensiveProgrammingBook/', label = 'Offensive Programming Book') )) # provides following result # "Refer to \href{https://neonira.github.io/offensiveProgrammingBook/}{Offensive Programming Book}."print(generateReference( list(url = 'https://neonira.github.io/offensiveProgrammingBook/', label = 'Offensive Programming Book') )) # provides following result # "Refer to \href{https://neonira.github.io/offensiveProgrammingBook/}{Offensive Programming Book}."
Generate R documentation section
generateSection(sectionName_s_1, content_s)generateSection(sectionName_s_1, content_s)
sectionName_s_1 |
A single |
content_s |
An unconstrained |
A single string, containing the generated reference text. Can be appended several
times to elaborate a multiple reference text.
See references and examples below.
This function should not be used directly unless you need to write your own manual page generation program.
To generate a manual page directly, you would better use produceManualPage.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Refer to Writing R extensions to know more about using web references in R documentation.
Refer to Parsing Rd files by Duncan Murdoch.
generateSection('concept', 'meta programming') # "\\concept{meta programming}"generateSection('concept', 'meta programming') # "\\concept{meta programming}"
Generate table format in R documentation
generateTable(content_dt, alignement_s_1 = NA_character_, numberRows_b_1 = FALSE, showHeader_b_1 = TRUE)generateTable(content_dt, alignement_s_1 = NA_character_, numberRows_b_1 = FALSE, showHeader_b_1 = TRUE)
content_dt |
A |
alignement_s_1 |
A single |
numberRows_b_1 |
A single |
showHeader_b_1 |
A single |
A single string, containing potentially many embedded formatting strings.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Refer to
Writing R extensions
section Lists and Tables .
library(data.table) dt <- data.table::data.table(x = runif(3), y = letters[1:3]) generateTable(dt) # "\tabular{ll}{\n0.975343016441911 \tab a \cr\n # 0.647014946676791 \tab b \cr\n0.576294980244711 \tab c \cr\n}" generateTable(dt, numberRows_b_1 = TRUE) # "\tabular{rll}{\n1 \tab 0.11690619844012 \tab a \cr\n # 2 \tab 0.467709563905373 \tab b \cr\n3 \tab 0.957075224025175 \tab c \cr\n}"library(data.table) dt <- data.table::data.table(x = runif(3), y = letters[1:3]) generateTable(dt) # "\tabular{ll}{\n0.975343016441911 \tab a \cr\n # 0.647014946676791 \tab b \cr\n0.576294980244711 \tab c \cr\n}" generateTable(dt, numberRows_b_1 = TRUE) # "\tabular{rll}{\n1 \tab 0.11690619844012 \tab a \cr\n # 2 \tab 0.467709563905373 \tab b \cr\n3 \tab 0.957075224025175 \tab c \cr\n}"
Define a generation context to produce a manual page
GenerationContext(targetFolder_s_1 = tempdir(), overwrite_b_1 = FALSE, verbosity_b_1 = FALSE, useMarkers_b_1 = FALSE )GenerationContext(targetFolder_s_1 = tempdir(), overwrite_b_1 = FALSE, verbosity_b_1 = FALSE, useMarkers_b_1 = FALSE )
targetFolder_s_1 |
a single |
overwrite_b_1 |
a single |
verbosity_b_1 |
a single |
useMarkers_b_1 |
A single |
An object instance of class GenerationContext based on
environment.
| ◆ overwrite_b_1 | logical |
| ◆ self | environment |
| ◆ targetFolder_s_1 | character |
| ◆ useMarkers_b_1 | logical |
| ◆ verbosity_b_1 | logical |
Class name compliance is TRUE.
Class owns no function return type instrumentation.
Class owns no test case definitions.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Class InputContext class ProcessingContext class
and class ManualPageBuilder.
GenerationContext() GenerationContext(overwrite = TRUE, verbosity = TRUE)GenerationContext() GenerationContext(overwrite = TRUE, verbosity = TRUE)
Get R documentation standard section names
getStandardSectionNames(sort_b_1 = FALSE)getStandardSectionNames(sort_b_1 = FALSE)
sort_b_1 |
A single |
A vector of type characters, expressing section names.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Refer to Writing R extensions.
getStandardSectionNames() # [1] "name" "docType" "alias" "title" "description" # [6] "usage" "arguments" "details" "value" "custom_section" # [11] "references" "author" "note" "seealso" "examples" # [16] "keyword" "concept" "encoding" "synopsis" "Rdversion" # [21] "RdOpts" "Sexpr"getStandardSectionNames() # [1] "name" "docType" "alias" "title" "description" # [6] "usage" "arguments" "details" "value" "custom_section" # [11] "references" "author" "note" "seealso" "examples" # [16] "keyword" "concept" "encoding" "synopsis" "Rdversion" # [21] "RdOpts" "Sexpr"
Identify replacement variables in the generated manual page to ease their substitutions.
identifyReplacementVariables(filename_s)identifyReplacementVariables(filename_s)
filename_s |
An unconstrained |
When producing a manual page using produceManualPage function,
under format-driven mode, sections will be generated with a very simple content
based on format 'XXX_???' to ease post processing substitutions and
hand-crafted replacements.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Function produceManualPage and class
GenerationContext.
# identifyReplacementVariables('myfile.Rd')# identifyReplacementVariables('myfile.Rd')
Environment class InputContext. Defines and eases input context management.
InputContext(object_o_1, methodName_s_1 = NA_character_, packageName_s_1 = NA_character_, dataFilename_s_1 = NA_character_ )InputContext(object_o_1, methodName_s_1 = NA_character_, packageName_s_1 = NA_character_, dataFilename_s_1 = NA_character_ )
object_o_1 |
a single |
methodName_s_1 |
a single |
packageName_s_1 |
a single |
dataFilename_s_1 |
a single |
An object instance.
◆ beautifier |
list |
◆ class_kind |
character |
◆ class_name |
character |
◆ data_name |
NULL |
◆ dataFilename_s_1 |
character |
◆ file_name |
character |
◆ hack_description |
logical |
◆ instrumentationLevel |
list |
◆ kind |
double |
◆ kinds |
character |
◆ methodName_s_1 |
character |
◆ number_replacements |
integer |
◆ object_o_1 |
list |
◆ packageName_s_1 |
character |
◆ self |
environment |
◆ typeFactory_o_1 |
environment |
◆ use_markers |
logical |
■ buildMethodName()
■ generateConditionalMarker(force_b_1 = FALSE)
■ generateConditionalMarker(Generatorforce_b_1 = FALSE)
■ getFilename()
■ getKind()
■ getName()
■ markerGenerator()
■ produceAlias()
■ produceArguments()
■ produceAuthor()
■ produceConcept()
■ produceCustom_section()
■ produceDescription()
■ produceDetails()
■ produceDocType()
■ produceEncoding()
■ produceExamples()
■ produceFormat()
■ produceKeyword()
■ produceName()
■ produceNote()
■ produceRdOpts()
■ produceRdversion()
■ produceReferences()
■ produceSeealso()
■ produceSexpr()
■ produceSource()
■ produceSynopsis()
■ produceTitle()
■ produceUsage()
■ produceValue()
■ retrieveStrategy()
■ setUseMarkers(value_b_1)
Class name compliance is TRUE.
Class owns no function return type instrumentation.
Class owns no test case definitions.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Class GenerationContext class ProcessingContext class
and class ManualPageBuilder.
ic1 <- InputContext(NULL) ic2 <- InputContext(NULL, 'append', package = 'my.package.name')ic1 <- InputContext(NULL) ic2 <- InputContext(NULL, 'append', package = 'my.package.name')
Interpret results of function
ManualPageBuilder
interpretResults(manualPageGenerationResults_l)interpretResults(manualPageGenerationResults_l)
manualPageGenerationResults_l |
A |
This function checks for presence of content that should be present in a well formated and documented function manual page. It provides hints. You could follow those hints to produce great documentation.
Provides output that allows to know which sections has been generated and which sections are missing or probably missing.
When producing a manual page using ManualPageBuilder,
keeping the result in a R variable allows you to interpret this
result at any time in the future. This is helpful when working incrementally
to produce a fully automated generation scheme for a given manual page.
See examples below.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
ic <- InputContext(NULL, 'append', packageName_s_1 = 'wyz.code.rdoc') res <- produceManualPage(ic) # WARNING: File /tmp/RtmpYIampA/append.Rd # checkRd: (5) /tmp/RtmpYIampA/append.Rd:0-19: Must have a \description interpretResults(res) # filename is /tmp/RtmpYIampA/append.Rd [OVERWRITTEN] # generated 8 sections: name, alias, title, usage, arguments, author, keyword, encoding # missing 3 sections: description, value, examples # probably missing 1 section: detailsic <- InputContext(NULL, 'append', packageName_s_1 = 'wyz.code.rdoc') res <- produceManualPage(ic) # WARNING: File /tmp/RtmpYIampA/append.Rd # checkRd: (5) /tmp/RtmpYIampA/append.Rd:0-19: Must have a \description interpretResults(res) # filename is /tmp/RtmpYIampA/append.Rd [OVERWRITTEN] # generated 8 sections: name, alias, title, usage, arguments, author, keyword, encoding # missing 3 sections: description, value, examples # probably missing 1 section: details
Environment class ManualPageBuilder. Creates manual pages according to the given context.
ManualPageBuilder(inputContext_o_1, processingContext_o_1 = ProcessingContext(), generationContext_o_1 = GenerationContext())ManualPageBuilder(inputContext_o_1, processingContext_o_1 = ProcessingContext(), generationContext_o_1 = GenerationContext())
inputContext_o_1 |
The input context |
processingContext_o_1 |
The processing context |
generationContext_o_1 |
The generation context |
An object instance of class ManualPageBuilder.
◆ colorizer |
list |
◆ generationContext_o_1 |
environment |
◆ inputContext_o_1 |
environment |
◆ processingContext_o_1 |
environment |
◆ self |
environment |
◆ strategy |
list |
■ assembleManualPage(pieces_l)
■ buildManualPage()
■ documentContent()
■ getStrategy
■ interpretResults(result_l)
Class name compliance is TRUE.
Class owns no function return type instrumentation.
Class owns no test case definitions.
As an end-user, you may prefer to use function produceManualPage
as its usage is much more straightforward.
As a programmer, this class eases programmation of your own manual page builder. See examples below.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Class InputContext class ProcessingContext and
class GenerationContext.
ic <- InputContext(NULL, 'append', package = 'my.package.name') m <- ManualPageBuilder(ic) r <- m$buildManualPage() interpretResults(r)ic <- InputContext(NULL, 'append', package = 'my.package.name') m <- ManualPageBuilder(ic) r <- m$buildManualPage() interpretResults(r)
List package functions and provide informations about their intented usage.
opRdocInformation()opRdocInformation()
See opInformation value
description.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
opRdocInformation()opRdocInformation()
Environment class ProcessingContext. Defines and eases processing context management.
ProcessingContext(extraneous_l = list(), postProcessing_l = list())ProcessingContext(extraneous_l = list(), postProcessing_l = list())
extraneous_l |
An unconstrained named |
postProcessing_l |
An unconstrained named |
If a post processing function returns NULL, related section will be
removed from generated content. See examples below.
Post processing aims to put in action simple transformations, as changing
letter cases, or applying simple beautifying technics. See beautify.
An object instance of class ProcessingContext.
◆ extraneous_l |
list |
◆ postProcessing_l |
list |
◆ self |
environment |
■ verifyExtraneous(extraneous_l)
■ verifyPostProcessing(postProcessing_l)
Class name compliance is TRUE.
Class owns no function return type instrumentation.
Class owns no test case definitions.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Class InputContext class GenerationContext class
and class ManualPageBuilder.
pc <- ProcessingContext( extraneous_l = list( 'my section' = "a special dedicace to neonira", keyword = 'documentation', concept = 'documentation generation' ), postProcessing_l = list( 'my section' = function(content_s) { gsub('neonira', 'NEONIRA', content_s, fixed = TRUE) }, author = function(content_s) { NULL } # destroy section ) )pc <- ProcessingContext( extraneous_l = list( 'my section' = "a special dedicace to neonira", keyword = 'documentation', concept = 'documentation generation' ), postProcessing_l = list( 'my section' = function(content_s) { gsub('neonira', 'NEONIRA', content_s, fixed = TRUE) }, author = function(content_s) { NULL } # destroy section ) )
Produce object and methods manual pages from an object.
produceAllManualPagesFromObject(object_o_1, processingContext_o_1 = ProcessingContext(), generationContext_o_1 = GenerationContext(), packageName_s_1 = NA_character_)produceAllManualPagesFromObject(object_o_1, processingContext_o_1 = ProcessingContext(), generationContext_o_1 = GenerationContext(), packageName_s_1 = NA_character_)
object_o_1 |
The single |
processingContext_o_1 |
The processing context |
generationContext_o_1 |
The generation context |
packageName_s_1 |
a single |
This is an EXPERIMENTAL function. Prefer usage of function
produceManualPage instead.
It generates reliable individual manual pages that taken all together are not fully compatible with R way to express documentation.
In particular, expect duplicated aliases to appear, and some name weirdness also.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Use this function to save documentation text into a documentation file.
produceDocumentationFile(filename_s_1, content_s, generationContext_o_1)produceDocumentationFile(filename_s_1, content_s, generationContext_o_1)
filename_s_1 |
the target file name to use |
content_s |
An unconstrained vector of string values |
generationContext_o_1 |
The generation context object to consider for generation.
See |
STRATUM ▶ LAYER_1
PHASING ▶ BUILD
INTENT ▶ CONTENT_GENERATION
From a end-user perspective, this function should only be used indirectly through a
call to produceManualPage function.
Direct call is meaningful when crafting your own manual page builder code/program.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
fn <- tempfile() p <- produceDocumentationFile(basename(fn), c( generateSection('name', 'alpha'), generateSection('alias', 'alpha'), generateSection('keyword', 'documentation generation') ), GenerationContext(dirname(fn))) p # $filename # [1] "/tmp/RtmpSWZq4H/filee3c2700207f.Rd" # # $overwritten # [1] TRUE readLines(p$filename) # [1] "\name{alpha}" "\alias{alpha}" "\keyword{documentation generation}"fn <- tempfile() p <- produceDocumentationFile(basename(fn), c( generateSection('name', 'alpha'), generateSection('alias', 'alpha'), generateSection('keyword', 'documentation generation') ), GenerationContext(dirname(fn))) p # $filename # [1] "/tmp/RtmpSWZq4H/filee3c2700207f.Rd" # # $overwritten # [1] TRUE readLines(p$filename) # [1] "\name{alpha}" "\alias{alpha}" "\keyword{documentation generation}"
Use this function to produce a manual page.
produceManualPage(inputContext_o_1, processingContext_o_1 = ProcessingContext(), generationContext_o_1 = GenerationContext())produceManualPage(inputContext_o_1, processingContext_o_1 = ProcessingContext(), generationContext_o_1 = GenerationContext())
inputContext_o_1 |
The input context object to consider for generation.
See |
processingContext_o_1 |
The processing context object to consider for generation.
See |
generationContext_o_1 |
The generation context object to consider for generation.
See |
A list holding generation process information.
Use function interpretResults to get knowledge of generated
parts and remaining issues.
STRATUM ▶ LAYER_3
PHASING ▶ RUN
INTENT ▶ QUALITY_CONTROL
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
ic <- InputContext(NULL, 'append', packageName_s_1 = 'wyz.code.rdoc') res <- produceManualPage(ic) # WARNING: File /tmp/RtmpYIampA/append.Rd # checkRd: (5) /tmp/RtmpYIampA/append.Rd:0-19: Must have a \description interpretResults(res) # filename is /tmp/RtmpYIampA/append.Rd [OVERWRITTEN] # generated 8 sections: name, alias, title, usage, arguments, author, keyword, encoding # missing 3 sections: description, value, examples # probably missing 1 section: detailsic <- InputContext(NULL, 'append', packageName_s_1 = 'wyz.code.rdoc') res <- produceManualPage(ic) # WARNING: File /tmp/RtmpYIampA/append.Rd # checkRd: (5) /tmp/RtmpYIampA/append.Rd:0-19: Must have a \description interpretResults(res) # filename is /tmp/RtmpYIampA/append.Rd [OVERWRITTEN] # generated 8 sections: name, alias, title, usage, arguments, author, keyword, encoding # missing 3 sections: description, value, examples # probably missing 1 section: details
Generation package cross reference in R documentation
producePackageLink(packageName_s_1, topicName_s_1)producePackageLink(packageName_s_1, topicName_s_1)
packageName_s_1 |
A single |
topicName_s_1 |
A single |
A single string, containing the generated package link.
See references and examples below.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Refer to Writing R extensions section 2.5, to know more about using cross references in R documentation.
See option link creation using function generateOptionLink.
producePackageLink('tools', 'checkRd') #[1] "\\link{tools:checkRd}{tools:checkRd}"producePackageLink('tools', 'checkRd') #[1] "\\link{tools:checkRd}{tools:checkRd}"
Provides all R documentation markup tags a.k.a keywords
rdocKeywords(asList_b_1 = FALSE)rdocKeywords(asList_b_1 = FALSE)
asList_b_1 |
A single |
A vector of type characters, containing all R documentation keywords,
when parameter asList_b_1 is FALSE. Otherwise a
list organizing this same content.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
Refer to Writing R extensions.
rdocKeywords()rdocKeywords()
Create a sentence from given content
sentensize(x_s, ..., punctuationCharacter_s_1 = ".")sentensize(x_s, ..., punctuationCharacter_s_1 = ".")
x_s |
An unconstrained |
... |
additional arguments (should be convertible to |
punctuationCharacter_s_1 |
the punctuation |
Collate all provided arguments, then normalize spaces.
Finally, ensure capitalization of first letter and final colon.
A single string.
There is no way to ask for a different final punctuation mark. If you need to
do so, either create your own helper function or simply sub
provided result.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
sentensize('a quick brown FOX jumps\tover', 'the lazy dog') # "A quick brown FOX jumps over the lazy dog." sentensize('a simple', ' question\t', punctuationCharacter_s_1 = '?') # "A simple question?"sentensize('a quick brown FOX jumps\tover', 'the lazy dog') # "A quick brown FOX jumps over the lazy dog." sentensize('a simple', ' question\t', punctuationCharacter_s_1 = '?') # "A simple question?"
Use this function to exploit prepared and customized shortcuts.
shortcuts(arguments_s = character(), doubleEscape_b_1 = TRUE)shortcuts(arguments_s = character(), doubleEscape_b_1 = TRUE)
arguments_s |
A |
doubleEscape_b_1 |
A single |
A list with following names
doc |
very common single R documentation keywords |
constants |
very common R constants used in R documentation |
types |
very common R types used in R documentation |
args |
function arguments ready to use in R documentation |
The names are all turned to lowercase.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
shortcuts(formalArgs(GenerationContext))shortcuts(formalArgs(GenerationContext))
Verify documentation file compliance to R documentation scheme.
verifyDocumentationFile(filename_s_1)verifyDocumentationFile(filename_s_1)
filename_s_1 |
A single |
Echoes on stdout status of documentation verification, as done by
tools:checkRd.
Fabien Gelineau <[email protected]>
Maintainer: Fabien Gelineau <[email protected]>
# verifyDocumentationFile("myfile.Rd")# verifyDocumentationFile("myfile.Rd")