11 Generating R documentation

When your code uses offensive programming features, it becomes much easier to generate R documentation, as now, several information might be deduced and reused for manual pages composition. Let’s see how.

11.1 Automated R documentation generation

Using package wyz.code.rdoc, manual pages .Rd files stored in man folder in a package context can be automatically created and filled up nearly to completion, depending on the level of offensive programming instrumentation of your code.

Generated manual pages uses English language. Feel free to modify produced English, to match your own English flavor, if needed.

The level of your R code instrumentation will impact the quality of the generation and your review work depth and time. When using both function return type instrumentation and test case instrumentation, expects produced manual page content to be fully generated and ready for review.

No automated generation of manual page is possible when your code is not offensive programming instrumented. In such a case, rely either on standard R tools to generate documentation or use package wyz.code.rdoc to create the artifact program that will reduce the burden of documentation generation.

11.2 Focus on R documentation generation

Package wyz.code.rdoc generates manual page sections, presented below with their information source and your remaining duties.

R manual section information source your duty
name R code none
alias R code none, unless you want to add extraneous aliases
title R code none
usage R code none
arguments R code none
value R code none if your code is function return type instrumented. Otherwise, you will have to write explicitly this part.
details R code you may complete this part that is generated when your code is function test case instrumented.
references your instruction Generated from instructions you may provide.
author package DESCRIPTION none
seealso your instruction Generated from instructions you may provide.
keyword your instruction Generated from instructions you may provide.
examples R code none when your code is function test case instrumented.
concept your instruction Generated from instructions you may provide.

Missing sections can be added on your instruction when generating manual pages. Package wyz.code.rdoc provides a convenient and easy way to do so.

The generated manual page can be used as-is, and should be immediately viewable and usable. From a format point of view, it complies with .Rd file syntax. From a content point of view, generated content aims to be reliable and express in human readable English wherever this makes sense. Indeed, you may bring desired enhancements to generated English sentences as you want.

Generated manual page requires review. You may add extraneous content, modify provided content and beautify the result. See known limits section 9.3 to know more.

11.3 package wyz.code.rdoc utilities

The package wyz.code.rdoc can be used to produce R documentation parts and R documentation generation programs.

Here under are presented a few utilities that will greatly help you in producing high quality manual pages. Please, take time to read the full paragraph as it will mind you about some very convenient R functions to produces R code documentation snippets. For more information, refer to respective manual pages.

11.3.1 Generate a R documentation section

Use function generateSection to generate a standard manual page section. Provide section name as first argument, and content as second.

This function does not allow you to generate a customized non standard manual page section. To do so, use generateContent.

11.3.2 Format an English sentence

Use function sentensize to format a sentence.

This functions ensures sentence starts with an upper-cased letter, adds a final dot if missing, and normalizes spaces, to ease readability.

11.3.4 Generate cross-ref to other R package

Use function generateSpecialLink to generate a R documentation cross-ref to any other R package.

11.4 Manual pages generation

Simply use generateDocumentationContent to do so.

11.4.2 Method manual page

Use keyword method to generate a dedicated manual page for an S3 method.

object <- AdditionTCFIG1()
package_name <- 'zorg'

refs <- list(
  list(url = 'https://cran.r-project.org/doc/manuals/R-exts.html',
       label = 'Writing R extensions',
       comment = 'to know more about R documentation requirements'),
  list(url = 'https://www.burns-stat.com/pages/Tutor/R_inferno.pdf',
       label = 'The R Inferno',
       comment = 'to discover some well-known R weirdness')

extra_method <- list(
  keyword = c('classes', 'environment', 'utilities', 'misc'),
  concept = c('evaluation mode', 'standard evaluation',
              'function return type evaluation', 'parameter check evaluation'),
  references = c(sentensize(paste('see',
                                  generateContent('wyz.code.offensiveProgramming', 'code'),
                                  'package documentation')),
                 sentensize(paste('You may read',
                                                  'href', 'Offensive Programming Book'),
                                  'to get introduction and expert advices on offensive programming')),
  seealso = c(sentensize(paste('see',
                               'to call interactively an offensive programming function, whether instrumented or not.')),
                               'to reuse on-demand instrumented offensive programming function tests'))

# explicit invocation for method
generateDocumentationContent(target_folder, 'method', 'addMultiDouble',
                             object, package_name,
                             extra_method, overwrite_b_1 = TRUE)

Note how parameter extra_method allows you to provide specific content as instruction to be considered for manual page generation. The extraneous content must be a list, where names are manual page sections, and where content is R documentation content.

You may use function generateDocumentationContent to generate your own R documentation generation scripts. This allows you to generate programmatically your manual pages, in a customized way.

Note that parameter package_name is the name of the target package you want to generate documentation for. Here, files are taken from the wyz.code.offensiveProgramming package, and documentation is generated for package zorg. Really useful when programming, not so useful when used interactively.

11.4.4 Package manual page

Use keyword class to generate a summary manual page for your package. Provide explicitly, all the class names you desired to emphase over.

Result is
Most important package entries are
See \code{wyz.code.offensiveProgramming} package documentation.

You may read \href{https://neonira.github.io/offensiveProgrammingBook/}{Offensive Programming Book} to get introduction and expert advices on offensive programming.

Refer to \href{https://cran.r-project.org/doc/manuals/R-exts.html}{Writing R extensions} to know more about R documentation requirements.

Maintainer: \packageMaintainer{zorg}
\concept{evaluation mode}
\concept{standard evaluation}
\concept{function return type evaluation}
\concept{parameter check evaluation}

11.4.6 and a special case, from a standalone function

When you own an offensive programming instrumented function, it is quite easy to get a pre-filled R documentation file from it. Be sure to pass NULL as value for parameter object_o_1.

Indeed, this convenience suffers from two drawbacks

  1. As the return type of the function is unknown, value section cannot be documented,
  2. As they are no test case definitions, examples section cannot be documented

11.5 Known-limits

Generation of manual pages can be quite tricky. Whereas package wyz.code.rdoc alleviates greatly the burden, some pitfalls remain. Here they are

  1. Generated manual page might not respect the maximum line length required by R CMD check, and this tool will provide explicit information about un-compliance. To solve issue, just split the content by adding carriage return wherever required.
  2. Generated documentation is quite stereotyped. Inject your instruction to customize the result.

11.6 Opportunities

Reuse can be made at several levels depending of your needs. Roughly speeking, you maty aim for one of these 3 levels of customization 1. just customize some textual information. Generate the pages using package wyz.code.rdoc and modify page contents manually is generally the best way to achieve this goal 1. customize some manual pages sections. Generate the pages using package wyz.code.rdoc while providing some dedicated context information. Refer to previous examples, and look at variables starting with extra_. They allow you to inject your customized content in targeted sections. 1. If you seek for fully customized manual page generation, then you may use package (ref:rd) to create your own R generation scheme. That way you will get the benefit of starting launched, using high-level R documentation generation functions, and also get the ability to reuse and customized provided generation scheme. This package uses only R code, and so you could get insight and reuse any part of it.