This use-case vignette is dedicated to some common manual page use case generation using package wyz.code.rdoc.
It may make sense for newcommers to read the tutorial vignette prior to read this vignette.
I will consider function append from base package as example. Any other R function may work as well.
b <- beautify()
examples <- list(
function() { append(1:5, 0:1, after = 3) }
)
ic <- InputContext(NULL, 'append')
pc <- ProcessingContext(
extraneous_l = list(
title = 'Vector Merging',
description = sentensize('add elements to a vector'),
details = paste('If the parameter', b$code('after'), 'is higher than' ,
b$code('x'), 'length,\n then insertion is done at the',
'end of the data structure'),
references = paste('Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)',
'The New S Language. Wadsworth & Brooks/Cole.'),
examples = convertExamples(examples, captureOutput_b_1n = FALSE)
),
postProcessing_l = list(
arguments = function(content_s) {
s <- sub('XXX_001', sentensize('the vector the values are to be appended to'),
content_s, fixed = TRUE)
s <- sub('XXX_002', sentensize('to be included in the modified vector'), s, fixed = TRUE)
s <- sub('XXX_003',
'a subscript, after which the values are to be appended',
s, fixed = TRUE)
s
}
)
)
td <- tempdir()
gc <- GenerationContext(td, overwrite = TRUE)
rv <- produceManualPage(ic, pc, gc)
File /tmp/Rtmphizv7q/append.Rd passes standard documentation checks NOTA BENE: Embedded new line characters in previous text are present for vignette format purpose only here, in particular to avoid horizontal scrollbars and to ease reading. Indeed, sometimes you will have to do so, to avoid producing too long lines in R documentations files, as this will generate a warning when running R CMD check. If you plan to publish your package on CRAN, you will have to resolve such warning cases.
readLines(rv$context$filename)
[1] "\\name{append}"
[2] "\\alias{append}"
[3] "\\title{Vector Merging}"
[4] "\\description{"
[5] "Add elements to a vector."
[6] "}"
[7] "\\usage{"
[8] "append(x, values, after = length(x))"
[9] "}"
[10] "\\arguments{"
[11] "\\item{x}{The vector the values are to be appended to.}"
[12] "\\item{values}{To be included in the modified vector.}"
[13] "\\item{after}{a subscript, after which the values are to be appended}"
[14] "}"
[15] "\\details{"
[16] "If the parameter \\code{after} is higher than \\code{x} length,"
[17] " then insertion is done at the end of the data structure"
[18] "}"
[19] "\\references{"
[20] "Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole."
[21] "}"
[22] "\\examples{"
[23] "# ------- example 1 -------"
[24] "append(1:5, 0:1, after = 3) "
[25] ""
[26] "}"
[27] "\\keyword{function}"
[28] "\\encoding{UTF-8}" 
generated append documentation
base R append documentation
Let’s consider following function, respectful of semantic naming as defined by offensive programming. Refer to Offensive programming book to get introduction and advanced knowledge on offensive programming advantages, practice and ecosystem.
The body is set to NULL for demonstration purpose and to prove that it does not interfere with documentation generation.
examples <- list(
function() { iterateOverSet(sample(LETTERS, 35, TRUE), FALSE) },
function() { iterateOverSet(as.character(1:9)) }
)
ic <- InputContext(NULL, 'iterateOverSet')
pc <- ProcessingContext(
extraneous_l = list(
examples = convertExamples(examples, captureOutput_b_1n = FALSE)
)
)
rv_op <- produceManualPage(ic, pc, gc)
File /tmp/Rtmphizv7q/iterateOverSet.Rd passes standard documentation checks readLines(rv_op$context$filename)
[1] "\\name{iterateOverSet}"
[2] "\\alias{iterateOverSet}"
[3] "\\title{Function iterateOverSet}"
[4] "\\description{"
[5] "Use this function to iterate over set."
[6] "}"
[7] "\\usage{"
[8] "iterateOverSet(set_s, enforceUniqueness_b_1 = TRUE)"
[9] "}"
[10] "\\arguments{"
[11] "\\item{set_s}{an unconstrained \\emph{\\code{vector}} of \\emph{\\code{string}} values representing the set}"
[12] "\\item{enforceUniqueness_b_1}{a single \\emph{\\code{boolean}} value representing the enforce uniqueness}"
[13] "}"
[14] "\\examples{"
[15] "# ------- example 1 -------"
[16] "iterateOverSet(sample(LETTERS, 35, TRUE), FALSE) "
[17] ""
[18] "# ------- example 2 -------"
[19] "iterateOverSet(as.character(1:9)) "
[20] ""
[21] "}"
[22] "\\keyword{function}"
[23] "\\encoding{UTF-8}" 
generated append documentation
Main differences with standard R function generation are, using semantic naming scheme, you do not have to
You can still change or adapt provided content by a post processing whenever and wherever needed to meet sharper documentation level.
I will consider class named MeltingPot_Env to produce an object based on an environment containing several functions.
source(findFilesInPackage('classes', 'wyz.code.offensiveProgramming')[1])
ic <- InputContext(MeltingPot_Env())
rv <- produceManualPage(ic, generationContext = gc)
File /tmp/Rtmphizv7q/MeltingPot_Env-class.Rd passes standard documentation checks NOTA BENE: I use default processing context here. This means, only defaultly valuable documentation sections will be filled-in.
readLines(rv$context$filename)
[1] "\\name{MeltingPot_Env-class}"
[2] "\\docType{class}"
[3] "\\alias{MeltingPot_Env-class}"
[4] "\\alias{MeltingPot_Env}"
[5] "\\title{Class MeltingPot_Env}"
[6] "\\description{"
[7] "Environment class MeltingPot_Env."
[8] "}"
[9] "\\usage{"
[10] "MeltingPot_Env()"
[11] "}"
[12] "\\value{"
[13] "An \\emph{\\code{object}} instance of \\emph{\\code{environment}} class \\emph{\\bold{\\code{\\link{MeltingPot_Env}}}}."
[14] "}"
[15] "\\section{Information}{"
[16] "\\subsection{Environment fields}{"
[17] "\\tabular{lll}{"
[18] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{self} \\tab environment \\cr"
[19] "}"
[20] "}"
[21] "\\subsection{Environment methods}{"
[22] "\\cr \\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{add3length}\\code{(x_i_3l, y_i_3l = 1:3)}\\cr"
[23] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{addDouble}\\code{(x_d, y_d)}\\cr"
[24] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{addInteger}\\code{(x_i, y_i)}\\cr"
[25] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{addMultiDouble}\\code{(...)}\\cr"
[26] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{addMultiInteger}\\code{(x_i, ...)}\\cr"
[27] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{addNumeric}\\code{(x_n, y_n)}\\cr"
[28] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{blabla}\\code{(a_s = \"bla\", b_s = c(\"bli\", \"blo\", \"blu\"))}\\cr"
[29] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{divideByZero}\\code{(x_n)}\\cr"
[30] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{echo}\\code{(x_s = \"hello world\")}\\cr"
[31] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{generateError}\\code{()}\\cr"
[32] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{generateWarning}\\code{()}"
[33] "}"
[34] "\\subsection{offensive programming - semantic naming}{"
[35] "Class name compliance is \\emph{\\code{FALSE}}."
[36] "}"
[37] "\\subsection{offensive programming - function return types}{"
[38] "Class owns no function return type instrumentation."
[39] "}"
[40] "\\subsection{offensive programming - test case definitions}{"
[41] "Class owns no test case definitions."
[42] "}"
[43] "\\subsection{offensive programming - examples}{"
[44] "mpe <- MeltingPot_Env()"
[45] "}"
[46] "}"
[47] "\\keyword{class}"
[48] "\\encoding{UTF-8}" 
generated append documentation
I will consider class named Zorg to produce an object based on an environment containing several functions. This class is partially offensive programming instrumented.
readLines(rv$context$filename)
[1] "\\name{Zorg-class}"
[2] "\\docType{class}"
[3] "\\alias{Zorg-class}"
[4] "\\alias{Zorg}"
[5] "\\title{Class Zorg}"
[6] "\\description{"
[7] "Environment class Zorg."
[8] "}"
[9] "\\usage{"
[10] "Zorg()"
[11] "}"
[12] "\\value{"
[13] "An \\emph{\\code{object}} instance of \\emph{\\code{environment}} class \\emph{\\bold{\\code{\\link{Zorg}}}}."
[14] "}"
[15] "\\section{Information}{"
[16] "\\subsection{Environment fields}{"
[17] "\\tabular{lll}{"
[18] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{function_name} \\tab NULL \\cr"
[19] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{function_return_types} \\tab list \\cr"
[20] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{self} \\tab environment \\cr"
[21] "}"
[22] "}"
[23] "\\subsection{Environment methods}{"
[24] "\\cr \\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{f}\\code{(x_d)}\\cr"
[25] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{h}\\code{(x_d)}"
[26] "}"
[27] "\\subsection{offensive programming - semantic naming}{"
[28] "Class name compliance is \\emph{\\code{TRUE}}."
[29] "}"
[30] "\\subsection{offensive programming - function return types}{"
[31] "Class owns partial function return type instrumentation."
[32] "\\tabular{rr}{\\code{function_name} \\tab \\code{return_value}\\cr"
[33] ""
[34] "\\bold{f} \\tab x_d \\cr"
[35] "}"
[36] "}"
[37] "\\subsection{offensive programming - test case definitions}{"
[38] "Class owns no test case definitions."
[39] "}"
[40] "\\subsection{offensive programming - examples}{"
[41] "z <- Zorg()"
[42] "}"
[43] "}"
[44] "\\keyword{class}"
[45] "\\encoding{UTF-8}" 
generated append documentation
There exists only very few differences between standard R and offensive programming class documentation generation. Using the later allows to benefit from instrumentation and allows to run dynamic checks instead of static checks.
I will consider class named Bu_S3 to produce an object based on S3 class scheme containing several functions.
readLines(rv$context$filename)
[1] "\\name{Bu_S3-class}"
[2] "\\docType{class}"
[3] "\\alias{Bu_S3-class}"
[4] "\\alias{Bu_S3}"
[5] "\\title{Class Bu_S3}"
[6] "\\description{"
[7] "S3 class Bu_S3."
[8] "}"
[9] "\\usage{"
[10] "Bu_S3(x_l = list(l = letters, d = 0:9))"
[11] "}"
[12] "\\arguments{"
[13] "\\item{x_l}{an unconstrained \\emph{\\code{list}} representing the x}"
[14] "}"
[15] "\\value{"
[16] "An \\emph{\\code{object}} instance of \\emph{\\code{S3}} class \\emph{\\bold{\\code{\\link{Bu_S3}}}}."
[17] "}"
[18] "\\section{Information}{"
[19] "\\subsection{S3 fields}{"
[20] "\\tabular{lll}{"
[21] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{d} \\tab integer \\cr"
[22] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{l} \\tab character \\cr"
[23] "}"
[24] "}"
[25] "\\subsection{S3 methods}{"
[26] "\\cr \\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{alpha}\\code{(x, msg_s = \"\", ...)}\\cr"
[27] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{print}\\code{(x, ...)}"
[28] "}"
[29] "\\subsection{offensive programming - semantic naming}{"
[30] "Class name compliance is \\emph{\\code{FALSE}}."
[31] "}"
[32] "\\subsection{offensive programming - function return types}{"
[33] "Class owns no function return type instrumentation."
[34] "}"
[35] "\\subsection{offensive programming - test case definitions}{"
[36] "Class owns no test case definitions."
[37] "}"
[38] "\\subsection{offensive programming - examples}{"
[39] "bs <- Bu_S3(x_l = list(l = letters, d = 0:9))"
[40] "}"
[41] "}"
[42] "\\keyword{class}"
[43] "\\encoding{UTF-8}" 
generated append documentation
I will consider class named Addition_TCFI_Partial_S3 to produce an object based on a S3 class containing several functions. This class is partially offensive programming instrumented.
readLines(rv$context$filename)
[1] "\\name{Addition_TCFI_Partial_S3-class}"
[2] "\\docType{class}"
[3] "\\alias{Addition_TCFI_Partial_S3-class}"
[4] "\\alias{Addition_TCFI_Partial_S3}"
[5] "\\title{Class Addition_TCFI_Partial_S3}"
[6] "\\description{"
[7] "S3 class Addition_TCFI_Partial_S3."
[8] "}"
[9] "\\usage{"
[10] "Addition_TCFI_Partial_S3()"
[11] "}"
[12] "\\value{"
[13] "An \\emph{\\code{object}} instance of \\emph{\\code{S3}} class \\emph{\\bold{\\code{\\link{Addition_TCFI_Partial_S3}}}}."
[14] "}"
[15] "\\section{Information}{"
[16] "\\subsection{S3 fields}{"
[17] "\\tabular{lll}{"
[18] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{function_return_types} \\tab list \\cr"
[19] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{label} \\tab character \\cr"
[20] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{test_case_definitions} \\tab list \\cr"
[21] "}"
[22] "}"
[23] "\\subsection{S3 methods}{"
[24] "\\cr \\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{addInteger}\\code{(object_o_1, x_i, y_i)}\\cr"
[25] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{addNumeric}\\code{(object_o_1, x_n, y_n)}\\cr"
[26] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{generateError}\\code{(object_o_1)}\\cr"
[27] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{generateWarning2}\\code{(object_o_1)}"
[28] "}"
[29] "\\subsection{offensive programming - semantic naming}{"
[30] "Class name compliance is \\emph{\\code{FALSE}}."
[31] "}"
[32] "\\subsection{offensive programming - function return types}{"
[33] "Class owns partial function return type instrumentation."
[34] "\\tabular{rr}{\\code{function_name} \\tab \\code{return_value}\\cr"
[35] ""
[36] "\\bold{addNumeric} \\tab x_n \\cr"
[37] "\\bold{generateError} \\tab x_er \\cr"
[38] "}"
[39] "}"
[40] "\\subsection{offensive programming - test case definitions}{"
[41] "Class owns partial test case definitions."
[42] "\\tabular{rr}{\\code{function_name} \\tab \\code{recorded_tests}\\cr"
[43] ""
[44] "\\bold{addInteger} \\tab 9 \\cr"
[45] "\\bold{generateError} \\tab 1 \\cr"
[46] "}"
[47] "}"
[48] "\\subsection{offensive programming - examples}{"
[49] "\\preformatted{library(\"data.table\")"
[50] "library(\"wyz.code.offensiveProgramming\")"
[51] ""
[52] "atcfips <- Addition_TCFI_Partial_S3()"
[53] "tcnum <- 7 # [1,10]"
[54] ""
[55] "# standard_R_evaluation mode"
[56] "se <- EvaluationMode(defineEvaluationMode()[1])"
[57] "ser <- runTestCase(atcfips, tcnum , se)"
[58] ""
[59] "# type_checking_enforcement mode"
[60] "tc <- EvaluationMode(defineEvaluationMode()[3])"
[61] "tcr <- runTestCase(atcfips, tcnum, tc)}"
[62] "}"
[63] "}"
[64] "\\keyword{class}"
[65] "\\encoding{UTF-8}" 
generated append documentation
There exists only very few differences between standard R and offensive programming class documentation generation. Using the later allows to benefit from instrumentation and allows to run dynamic checks instead of static checks.
I will consider class named Person_S4 to produce an object based on S4 class scheme containing several functions.
readLines(rv$context$filename)
[1] "\\name{Person_S4-class}"
[2] "\\docType{class}"
[3] "\\alias{Person_S4-class}"
[4] "\\alias{Person_S4}"
[5] "\\title{Class Person_S4}"
[6] "\\description{"
[7] "S4 class Person_S4."
[8] "}"
[9] "\\usage{"
[10] "Person_S4(...)"
[11] "}"
[12] "\\arguments{"
[13] "\\item{...}{additional arguments.}"
[14] "}"
[15] "\\value{"
[16] "An \\emph{\\code{object}} instance of \\emph{\\code{S4}} class \\emph{\\bold{\\code{\\link{Person_S4}}}}."
[17] "}"
[18] "\\section{Information}{"
[19] "\\subsection{S4 fields}{"
[20] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\bold{name} character\\cr"
[21] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\bold{age} double"
[22] "}"
[23] "\\subsection{S4 methods}{"
[24] "\\cr \\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{name}\\code{(o_)}"
[25] "}"
[26] "\\subsection{offensive programming - semantic naming}{"
[27] "Class name compliance is \\emph{\\code{FALSE}}."
[28] "}"
[29] "\\subsection{offensive programming - function return types}{"
[30] "Class owns no function return type instrumentation."
[31] "}"
[32] "\\subsection{offensive programming - test case definitions}{"
[33] "Class owns no test case definitions."
[34] "}"
[35] "\\subsection{offensive programming - examples}{"
[36] "ps <- Person_S4(...)"
[37] "}"
[38] "}"
[39] "\\keyword{class}"
[40] "\\encoding{UTF-8}" 
generated append documentation
I will consider class named Addition_TCFI_Partial_S4 to produce an object based on a S4 class containing several functions. This class is partially offensive programming instrumented.
readLines(rv$context$filename)
[1] "\\name{Addition_TCFI_Partial_S4-class}"
[2] "\\docType{class}"
[3] "\\alias{Addition_TCFI_Partial_S4-class}"
[4] "\\alias{Addition_TCFI_Partial_S4}"
[5] "\\title{Class Addition_TCFI_Partial_S4}"
[6] "\\description{"
[7] "S4 class Addition_TCFI_Partial_S4."
[8] "}"
[9] "\\usage{"
[10] "Addition_TCFI_Partial_S4(...)"
[11] "}"
[12] "\\arguments{"
[13] "\\item{...}{additional arguments.}"
[14] "}"
[15] "\\value{"
[16] "An \\emph{\\code{object}} instance of \\emph{\\code{S4}} class \\emph{\\bold{\\code{\\link{Addition_TCFI_Partial_S4}}}}."
[17] "}"
[18] "\\section{Information}{"
[19] "\\subsection{S4 fields}{"
[20] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\bold{function_return_types} list\\cr"
[21] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\bold{test_case_definitions} list"
[22] "}"
[23] "\\subsection{S4 methods}{"
[24] "\\cr \\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{addInteger}\\code{(object_o_1, x_i, y_i)}\\cr"
[25] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{addNumeric}\\code{(object_o_1, x_d, y_d)}\\cr"
[26] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{generateError}\\code{(object_o_1)}\\cr"
[27] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{generateWarning}\\code{(object_o_1, x_i, y_i)}"
[28] "}"
[29] "\\subsection{offensive programming - semantic naming}{"
[30] "Class name compliance is \\emph{\\code{FALSE}}."
[31] "}"
[32] "\\subsection{offensive programming - function return types}{"
[33] "Class owns partial function return type instrumentation."
[34] "\\tabular{rr}{\\code{function_name} \\tab \\code{return_value}\\cr"
[35] ""
[36] "\\bold{addInteger} \\tab x_n \\cr"
[37] "\\bold{generateError} \\tab x_er \\cr"
[38] "}"
[39] "}"
[40] "\\subsection{offensive programming - test case definitions}{"
[41] "Class owns partial test case definitions."
[42] "\\tabular{rr}{\\code{function_name} \\tab \\code{recorded_tests}\\cr"
[43] ""
[44] "\\bold{addInteger} \\tab 9 \\cr"
[45] "\\bold{generateError} \\tab 1 \\cr"
[46] "}"
[47] "}"
[48] "\\subsection{offensive programming - examples}{"
[49] "\\preformatted{library(\"data.table\")"
[50] "library(\"wyz.code.offensiveProgramming\")"
[51] ""
[52] "atcfips <- Addition_TCFI_Partial_S4(...)"
[53] "tcnum <- 1 # [1,10]"
[54] ""
[55] "# standard_R_evaluation mode"
[56] "se <- EvaluationMode(defineEvaluationMode()[1])"
[57] "ser <- runTestCase(atcfips, tcnum , se)"
[58] ""
[59] "# type_checking_enforcement mode"
[60] "tc <- EvaluationMode(defineEvaluationMode()[3])"
[61] "tcr <- runTestCase(atcfips, tcnum, tc)}"
[62] "}"
[63] "}"
[64] "\\keyword{class}"
[65] "\\encoding{UTF-8}" 
generated append documentation
There exists only very few differences between standard R and offensive programming class documentation generation. Using the later allows to benefit from instrumentation and allows to run dynamic checks instead of static checks.
I will consider class named Person_RC to produce an object based on RC class scheme containing several functions.
readLines(rv$context$filename)
[1] "\\name{Person_RC-class}"
[2] "\\docType{class}"
[3] "\\alias{Person_RC-class}"
[4] "\\alias{Person_RC}"
[5] "\\title{Class Person_RC}"
[6] "\\description{"
[7] "RC class Person_RC."
[8] "}"
[9] "\\usage{"
[10] "Person_RC(...)"
[11] "}"
[12] "\\arguments{"
[13] "\\item{...}{additional arguments.}"
[14] "}"
[15] "\\value{"
[16] "An \\emph{\\code{object}} instance of \\emph{\\code{RC}} class \\emph{\\bold{\\code{\\link{Person_RC}}}}."
[17] "}"
[18] "\\section{Information}{"
[19] "\\subsection{RC class definition}{"
[20] "Class Person_RC inherits from envRefClass."
[21] "}"
[22] "\\subsection{RC fields}{"
[23] "\\tabular{lll}{"
[24] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{age} \\tab integer \\cr"
[25] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{name} \\tab character \\cr"
[26] "}"
[27] "}"
[28] "\\subsection{RC methods}{"
[29] "\\cr \\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{setAge}\\code{(anAge)}\\cr"
[30] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{setName}\\code{(aname)}"
[31] "}"
[32] "\\subsection{offensive programming - semantic naming}{"
[33] "Class name compliance is \\emph{\\code{FALSE}}."
[34] "}"
[35] "\\subsection{offensive programming - function return types}{"
[36] "Class owns no function return type instrumentation."
[37] "}"
[38] "\\subsection{offensive programming - test case definitions}{"
[39] "Class owns no test case definitions."
[40] "}"
[41] "\\subsection{offensive programming - examples}{"
[42] "prc <- Person_RC(...)"
[43] "}"
[44] "}"
[45] "\\keyword{class}"
[46] "\\encoding{UTF-8}" 
generated append documentation
I will consider class named Addition_TCFI_Partial_RC to produce an object based on an RC class containing several functions. This class is partially offensive programming instrumented.
readLines(rv$context$filename)
[1] "\\name{Addition_TCFI_Partial_RC-class}"
[2] "\\docType{class}"
[3] "\\alias{Addition_TCFI_Partial_RC-class}"
[4] "\\alias{Addition_TCFI_Partial_RC}"
[5] "\\title{Class Addition_TCFI_Partial_RC}"
[6] "\\description{"
[7] "RC class Addition_TCFI_Partial_RC."
[8] "}"
[9] "\\usage{"
[10] "Addition_TCFI_Partial_RC(...)"
[11] "}"
[12] "\\arguments{"
[13] "\\item{...}{additional arguments.}"
[14] "}"
[15] "\\value{"
[16] "An \\emph{\\code{object}} instance of \\emph{\\code{RC}} class \\emph{\\bold{\\code{\\link{Addition_TCFI_Partial_RC}}}}."
[17] "}"
[18] "\\section{Information}{"
[19] "\\subsection{RC class definition}{"
[20] "Class Addition_TCFI_Partial_RC inherits from envRefClass."
[21] "}"
[22] "\\subsection{RC fields}{"
[23] "\\tabular{lll}{"
[24] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{function_return_types} \\tab list \\cr"
[25] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{label} \\tab character \\cr"
[26] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{test_case_definitions} \\tab list \\cr"
[27] "}"
[28] "}"
[29] "\\subsection{RC methods}{"
[30] "\\cr \\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{addInteger}\\code{(x_i, y_i)}\\cr"
[31] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{generateError}\\code{()}\\cr"
[32] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{generateErrorBis}\\code{()}\\cr"
[33] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{generateWarning}\\code{()}"
[34] "}"
[35] "\\subsection{offensive programming - semantic naming}{"
[36] "Class name compliance is \\emph{\\code{FALSE}}."
[37] "}"
[38] "\\subsection{offensive programming - function return types}{"
[39] "Class owns partial function return type instrumentation."
[40] "\\tabular{rr}{\\code{function_name} \\tab \\code{return_value}\\cr"
[41] ""
[42] "\\bold{addInteger} \\tab x_n \\cr"
[43] "\\bold{generateError} \\tab x_n \\cr"
[44] "\\bold{generateWarning} \\tab x_er \\cr"
[45] "}"
[46] "}"
[47] "\\subsection{offensive programming - test case definitions}{"
[48] "Class owns partial test case definitions."
[49] "\\tabular{rr}{\\code{function_name} \\tab \\code{recorded_tests}\\cr"
[50] ""
[51] "\\bold{addInteger} \\tab 9 \\cr"
[52] "\\bold{generateError} \\tab 1 \\cr"
[53] "\\bold{generateErrorBis} \\tab 1 \\cr"
[54] "}"
[55] "}"
[56] "\\subsection{offensive programming - examples}{"
[57] "\\preformatted{library(\"data.table\")"
[58] "library(\"wyz.code.offensiveProgramming\")"
[59] ""
[60] "atcfiprc <- Addition_TCFI_Partial_RC(...)"
[61] "tcnum <- 7 # [1,11]"
[62] ""
[63] "# standard_R_evaluation mode"
[64] "se <- EvaluationMode(defineEvaluationMode()[1])"
[65] "ser <- runTestCase(atcfiprc, tcnum , se)"
[66] ""
[67] "# type_checking_enforcement mode"
[68] "tc <- EvaluationMode(defineEvaluationMode()[3])"
[69] "tcr <- runTestCase(atcfiprc, tcnum, tc)}"
[70] "}"
[71] "}"
[72] "\\keyword{class}"
[73] "\\encoding{UTF-8}" 
generated append documentation
There exists only very few differences between standard R and offensive programming class documentation generation. Using the later allows to benefit from instrumentation and allows to run dynamic checks instead of static checks.
I will consider class named Accumulator_R6 to produce an object based on R6 class scheme containing several functions.
readLines(rv$context$filename)
[1] "\\name{Accumulator_R6-class}"
[2] "\\docType{class}"
[3] "\\alias{Accumulator_R6-class}"
[4] "\\alias{Accumulator_R6}"
[5] "\\title{Class Accumulator_R6}"
[6] "\\description{"
[7] "R6 class Accumulator_R6."
[8] "}"
[9] "\\usage{"
[10] "Accumulator_R6$new(...)"
[11] "}"
[12] "\\arguments{"
[13] "\\item{...}{additional arguments.}"
[14] "}"
[15] "\\value{"
[16] "An \\emph{\\code{object}} instance of \\emph{\\code{R6}} class \\emph{\\bold{\\code{\\link{Accumulator_R6}}}}."
[17] "}"
[18] "\\section{Information}{"
[19] "\\subsection{R6 class definition}{"
[20] "Lock class is \\code{FALSE}."
[21] "Lock objects is \\code{TRUE}."
[22] "Class portability is \\code{TRUE}."
[23] "}"
[24] "\\subsection{R6 public fields}{"
[25] "\\tabular{lll}{"
[26] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{sum} \\tab double \\cr"
[27] "}"
[28] "}"
[29] "\\subsection{R6 public methods}{"
[30] "\\cr \\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{add}\\code{(x = 1)}"
[31] "}"
[32] "\\subsection{offensive programming - semantic naming}{"
[33] "Class name compliance is \\emph{\\code{FALSE}}."
[34] "}"
[35] "\\subsection{offensive programming - function return types}{"
[36] "Class owns no function return type instrumentation."
[37] "}"
[38] "\\subsection{offensive programming - test case definitions}{"
[39] "Class owns no test case definitions."
[40] "}"
[41] "\\subsection{offensive programming - examples}{"
[42] "ar <- Accumulator_R6$new(...)"
[43] "}"
[44] "}"
[45] "\\keyword{class}"
[46] "\\encoding{UTF-8}" 
generated append documentation
I will consider class named Addition_TCFI_Partial_R6 to produce an object based on an R6 class containing several functions. This class is partially offensive programming instrumented.
readLines(rv$context$filename)
[1] "\\name{Addition_TCFI_Partial_R6-class}"
[2] "\\docType{class}"
[3] "\\alias{Addition_TCFI_Partial_R6-class}"
[4] "\\alias{Addition_TCFI_Partial_R6}"
[5] "\\title{Class Addition_TCFI_Partial_R6}"
[6] "\\description{"
[7] "R6 class Addition_TCFI_Partial_R6."
[8] "}"
[9] "\\usage{"
[10] "Addition_TCFI_Partial_R6$new(...)"
[11] "}"
[12] "\\arguments{"
[13] "\\item{...}{additional arguments.}"
[14] "}"
[15] "\\value{"
[16] "An \\emph{\\code{object}} instance of \\emph{\\code{R6}} class \\emph{\\bold{\\code{\\link{Addition_TCFI_Partial_R6}}}}."
[17] "}"
[18] "\\section{Information}{"
[19] "\\subsection{R6 class definition}{"
[20] "Lock class is \\code{FALSE}."
[21] "Lock objects is \\code{TRUE}."
[22] "Class portability is \\code{TRUE}."
[23] "}"
[24] "\\subsection{R6 public fields}{"
[25] "\\tabular{lll}{"
[26] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{sum} \\tab double \\cr"
[27] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{function_return_types} \\tab list \\cr"
[28] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{test_case_definitions} \\tab list \\cr"
[29] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{◆}}{\\\\u25c6}} \\tab \\bold{label} \\tab character \\cr"
[30] "}"
[31] "}"
[32] "\\subsection{R6 public methods}{"
[33] "\\cr \\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{addInteger}\\code{(x_i, y_i)}\\cr"
[34] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{generateError}\\code{()}\\cr"
[35] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{■}}{\\\\u25a0}} \\bold{generateWarning}\\code{()}"
[36] "}"
[37] "\\subsection{offensive programming - semantic naming}{"
[38] "Class name compliance is \\emph{\\code{FALSE}}."
[39] "}"
[40] "\\subsection{offensive programming - function return types}{"
[41] "Class owns partial function return type instrumentation."
[42] "\\tabular{rr}{\\code{function_name} \\tab \\code{return_value}\\cr"
[43] ""
[44] "\\bold{addInteger} \\tab x_n \\cr"
[45] "\\bold{generateError} \\tab x_er \\cr"
[46] "}"
[47] "}"
[48] "\\subsection{offensive programming - test case definitions}{"
[49] "Class owns partial test case definitions."
[50] "\\tabular{rr}{\\code{function_name} \\tab \\code{recorded_tests}\\cr"
[51] ""
[52] "\\bold{addInteger} \\tab 9 \\cr"
[53] "\\bold{generateError} \\tab 1 \\cr"
[54] "}"
[55] "}"
[56] "\\subsection{offensive programming - examples}{"
[57] "\\preformatted{library(\"data.table\")"
[58] "library(\"wyz.code.offensiveProgramming\")"
[59] ""
[60] "atcfipr <- Addition_TCFI_Partial_R6$new(...)"
[61] "tcnum <- 5 # [1,10]"
[62] ""
[63] "# standard_R_evaluation mode"
[64] "se <- EvaluationMode(defineEvaluationMode()[1])"
[65] "ser <- runTestCase(atcfipr, tcnum , se)"
[66] ""
[67] "# type_checking_enforcement mode"
[68] "tc <- EvaluationMode(defineEvaluationMode()[3])"
[69] "tcr <- runTestCase(atcfipr, tcnum, tc)}"
[70] "}"
[71] "}"
[72] "\\keyword{class}"
[73] "\\encoding{UTF-8}" 
generated append documentation
I will consider package named wyz.code.rdoc as example to generate a package manual page.
readLines(rv$context$filename)
[1] "\\name{wyz.code.rdoc-package}"
[2] "\\docType{package}"
[3] "\\alias{wyz.code.rdoc-package}"
[4] "\\alias{wyz.code.rdoc}"
[5] "\\title{\\packageTitle{wyz.code.rdoc}}"
[6] "\\description{"
[7] "\\packageDescription{wyz.code.rdoc}"
[8] "}"
[9] "\\usage{"
[10] "library(wyz.code.rdoc)"
[11] "}"
[12] "\\author{"
[13] "\\packageAuthor{wyz.code.rdoc}"
[14] ""
[15] "Maintainer: \\packageMaintainer{wyz.code.rdoc}"
[16] "}"
[17] "\\keyword{package}"
[18] "\\encoding{UTF-8}" 
generated append documentation
I will consider data named dummy to generate documentation from.
ic <- InputContext(dummy, dataFilename = 'dummy.csv')
pc <- ProcessingContext(
extraneous_l = list(
description = 'a dummy datafile for demonstration purpose',
format = 'a data.frame 9x2',
source = 'fake data - used only for demo'
),
postProcessing_l = list(
classification = function(content_s) NULL
)
)
rv <- produceManualPage(ic, pc, gc)
File /tmp/Rtmphizv7q/dummy.Rd passes standard documentation checks readLines(rv$context$filename)
[1] "\\name{dummy}"
[2] "\\docType{data}"
[3] "\\alias{dummy}"
[4] "\\title{Data set dummy}"
[5] "\\description{"
[6] "a dummy datafile for demonstration purpose"
[7] "}"
[8] "\\usage{"
[9] "dummy"
[10] "}"
[11] "\\keyword{datasets}"
[12] "\\encoding{UTF-8}"
[13] "\\format{"
[14] "a data.frame 9x2"
[15] "}"
[16] "\\source{"
[17] "fake data - used only for demo"
[18] "}" 
generated append documentation