wyz.code.rdoc use cases

Fabien GELINEAU

Last update 2020 - Q1

offensive programming - R documentation

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.

1 Manual page generation from a function

1.1 Standard R function

I will consider function append from base package as example. Any other R function may work as well.

1.1.1 code

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.

1.1.2 generated .Rd file

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}"                                                                                  

1.1.3 generated content as picture

generated append documentation

1.1.4 original content

base R append documentation

1.2 Semantic naming function

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.

iterateOverSet <- function(set_s, enforceUniqueness_b_1 = TRUE) {
  NULL
}

The body is set to NULL for demonstration purpose and to prove that it does not interfere with documentation generation.

1.2.1 code

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 

1.2.2 generated .Rd file

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}"                                                                                           

1.2.3 generated content as picture

generated append documentation

1.2.4 Main differences

Main differences with standard R function generation are, using semantic naming scheme, you do not have to

  1. provide content for arguments. It is automatically deduced from the semantic name you use
  2. provide a title. It is deduced from the function name.
  3. provide a description. It is also deduced from the function name.

You can still change or adapt provided content by a post processing whenever and wherever needed to meet sharper documentation level.

2 Manual page generation from an environment object

2.1 Standard R object

I will consider class named MeltingPot_Env to produce an object based on an environment containing several functions.

2.1.1 code

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.

2.1.2 generated .Rd file

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{&#x25C6;}}{\\\\u25c6}} \\tab \\bold{self} \\tab environment \\cr"                                        
[19] "}"                                                                                                                                                               
[20] "}"                                                                                                                                                               
[21] "\\subsection{Environment methods}{"                                                                                                                              
[22] "\\cr \\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\u25a0}} \\bold{add3length}\\code{(x_i_3l, y_i_3l = 1:3)}\\cr"                    
[23] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\u25a0}} \\bold{addDouble}\\code{(x_d, y_d)}\\cr"                                      
[24] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\u25a0}} \\bold{addInteger}\\code{(x_i, y_i)}\\cr"                                     
[25] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\u25a0}} \\bold{addMultiDouble}\\code{(...)}\\cr"                                      
[26] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\u25a0}} \\bold{addMultiInteger}\\code{(x_i, ...)}\\cr"                                
[27] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\u25a0}} \\bold{addNumeric}\\code{(x_n, y_n)}\\cr"                                     
[28] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\u25a0}} \\bold{blabla}\\code{(a_s = \"bla\", b_s = c(\"bli\", \"blo\", \"blu\"))}\\cr"
[29] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\u25a0}} \\bold{divideByZero}\\code{(x_n)}\\cr"                                        
[30] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\u25a0}} \\bold{echo}\\code{(x_s = \"hello world\")}\\cr"                              
[31] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\u25a0}} \\bold{generateError}\\code{()}\\cr"                                          
[32] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\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}"                                                                                                                                               

2.1.3 generated content as picture

generated append documentation

2.2 Offensive programming object

I will consider class named Zorg to produce an object based on an environment containing several functions. This class is partially offensive programming instrumented.

2.2.1 code

ic <- InputContext(Zorg())
rv <- produceManualPage(ic, generationContext = gc)
File /tmp/Rtmphizv7q/Zorg-class.Rd passes standard documentation checks 

2.2.2 generated .Rd file

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{&#x25C6;}}{\\\\u25c6}} \\tab \\bold{function_name} \\tab NULL \\cr"        
[19] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{&#x25C6;}}{\\\\u25c6}} \\tab \\bold{function_return_types} \\tab list \\cr"
[20] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{&#x25C6;}}{\\\\u25c6}} \\tab \\bold{self} \\tab environment \\cr"          
[21] "}"                                                                                                                                 
[22] "}"                                                                                                                                 
[23] "\\subsection{Environment methods}{"                                                                                                
[24] "\\cr \\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\u25a0}} \\bold{f}\\code{(x_d)}\\cr"                
[25] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\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}"                                                                                                                 

2.2.3 generated content as picture

generated append documentation

2.2.4 Main differences

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.

3 Manual page generation from an S3 object

3.1 Standard R object

I will consider class named Bu_S3 to produce an object based on S3 class scheme containing several functions.

3.1.1 code

ic <- InputContext(Bu_S3())
rv <- produceManualPage(ic, generationContext = gc)
File /tmp/Rtmphizv7q/Bu_S3-class.Rd passes standard documentation checks 

3.1.2 generated .Rd file

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{&#x25C6;}}{\\\\u25c6}} \\tab \\bold{d} \\tab integer \\cr"                      
[22] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{&#x25C6;}}{\\\\u25c6}} \\tab \\bold{l} \\tab character \\cr"                    
[23] "}"                                                                                                                                      
[24] "}"                                                                                                                                      
[25] "\\subsection{S3 methods}{"                                                                                                              
[26] "\\cr \\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\u25a0}} \\bold{alpha}\\code{(x, msg_s = \"\", ...)}\\cr"
[27] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\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}"                                                                                                                      

3.1.3 generated content as picture

generated append documentation

3.2 Offensive programming object

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.

3.2.1 code

source(findFilesInPackage('Addition_TCFI_Partial_S3.R', 'wyz.code.offensiveProgramming')[1])
ic <- InputContext(Addition_TCFI_Partial_S3())
rv <- produceManualPage(ic, generationContext = gc)
File /tmp/Rtmphizv7q/Addition_TCFI_Partial_S3-class.Rd passes standard documentation checks 

3.2.2 generated .Rd file

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{&#x25C6;}}{\\\\u25c6}} \\tab \\bold{function_return_types} \\tab list \\cr"          
[19] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{&#x25C6;}}{\\\\u25c6}} \\tab \\bold{label} \\tab character \\cr"                     
[20] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{&#x25C6;}}{\\\\u25c6}} \\tab \\bold{test_case_definitions} \\tab list \\cr"          
[21] "}"                                                                                                                                           
[22] "}"                                                                                                                                           
[23] "\\subsection{S3 methods}{"                                                                                                                   
[24] "\\cr \\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\u25a0}} \\bold{addInteger}\\code{(object_o_1, x_i, y_i)}\\cr"
[25] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\u25a0}} \\bold{addNumeric}\\code{(object_o_1, x_n, y_n)}\\cr"     
[26] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\u25a0}} \\bold{generateError}\\code{(object_o_1)}\\cr"            
[27] "\\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\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}"                                                                                                                           

3.2.3 generated content as picture

generated append documentation

3.2.4 Main differences

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.

4 Manual page generation from an S4 object

4.1 Standard R object

I will consider class named Person_S4 to produce an object based on S4 class scheme containing several functions.

4.1.1 code

ic <- InputContext(new('Person_S4', name = 'neonira'))
rv <- produceManualPage(ic, generationContext = gc)
File /tmp/Rtmphizv7q/Person_S4-class.Rd passes standard documentation checks 

4.1.2 generated .Rd file

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{&#x25C6;}}{\\\\u25c6}} \\bold{name} character\\cr"       
[21] "\\ifelse{latex}{\\out{$\\mapsto$}}{\\ifelse{html}{\\out{&#x25C6;}}{\\\\u25c6}} \\bold{age} double"               
[22] "}"                                                                                                               
[23] "\\subsection{S4 methods}{"                                                                                       
[24] "\\cr \\ifelse{latex}{\\out{$\\rightarrow$}}{\\ifelse{html}{\\out{&#x25A0;}}{\\\\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}"                                                                                               

4.1.3 generated content as picture