Still hand-crafting your Rdoc files?

May 4, 2020
By

[This article was first published on NEONIRA, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

[1]

If your still hand-crafting your R
documentation files, then you face a time consuming activity. Trying to
foresee time needed to get a documentation to an expected quality level
stays a real challenge.

The generic process to create an R
documentation file looks like

Whatever approach you use, traditional one using base
R
, or more modern ones like roxygen2,
this process requires iterations, and it is generally where it hurts to
work under scheduled time while guaranteeing the right level of
documentation quality. Not only the process is iterative, it is also
generally poorly industrializable.

Another approach is offered by package
wyz.code.rdoc, that is generating documentation
from code, by code. This allows much easier and deeper
industrialization level. It permits to create quite easily pieces of
R code to generate any
R documentation parts or the whole
documentation, according to your needs. Let’s see an example.

Produce documentation from code

Imagine, you need to create a documentation for following
dummy R function
that resides in a package named
lambdaPackage.

specialAddition <- function(x, ...) suppressWarnings(sum(unlist(list(x, ...)), 0L))

Using wyz.code.rdoc, here is the way to create
your documentation

library(wyz.code.rdoc)

# your documentation examples to consider
examples <- list(
  function() { specialAddition(1, 2, 3) },
  function() { specialAddition(1:3, 1:7, 1:11) },
  function() { specialAddition(as.list(1:13), 
                               c(1:4, Inf, -Inf, NaN), 
                               runif(13, 0, 19)) }
)

# your documentation complementary parts to consider 
shortcuts <- shortcuts(formalArgs(specialAddition), FALSE)
postprocessor <- shortcuts(formalArgs(specialAddition), TRUE)
pc <- ProcessingContext(
  extraneous_l = list(
    title = 'Special Addition',
    description = sentensize('add vector or list of numerics whatever', 
                             'their length'),
    value = sentensize(paste('a single', shortcuts$type$numeric, 'value')), 
    details = paste('Classical', shortcuts$doc$r, 
                    'warning messages about recycling are managed internally',
                    'and discarded by the function.'),
    examples = convertExamples(examples, captureOutput = FALSE)
  ),
  postProcessing_l = list(
    arguments = function(content_s) {
      sub('XXX_00\\d{1}', paste('a', postprocessor$type$vector, 'or', postprocessor$type$list,
                                'of', postprocessor$type$numeric, 'values'), 
          content_s, perl = TRUE)
    },
    author = function(content_s) NULL # remove authorship
  )
)

# The generation of the manual page
p <- produceManualPage(InputContext(NULL, 'specialAddition', 'lambdaPackage'),
                       pc, GenerationContext('~/tmp', overwrite = TRUE))
## File ~/tmp/specialAddition.Rd passes standard documentation checks

Generation process overview

Quite simple, as the process is straightforward

  1. provide your examples as a list of functions taking no parameter
  2. set a processing context, expressing sections to add, and any
    required post processing actions to get fully documented manual
    page,
  3. generate your R manual page using function
    produceManualPage
  4. Get immediate result of compliance against
    R documentation checks

Notice some important points

  1. Here, generated manual page
    1. is produced for a package and package name matters in such
      context,
    2. took into consideration your content and format customizations,
    3. has used the 3 examples you provided,
    4. patched at your demand the content of function arguments,
    5. removed at your demand authorship from the output
  2. Function shortcuts allows easy and
    convenient reuse of very common R
    documentation language markup sequences. You don’t have to learn
    these markup sequence, just have to known how to reuse those pieces.
  3. Produced manual page has gone through standard
    R documentation check tool to ensure
    documentation validity and to provide an immediate feedback.

Preview

Preview captured from RStudio.

Try it and become a fan

Main benefits of proposed approach are

  1. Nearly full coverage of the previously exposed
    R process
  2. High flexibility customization
  3. Ease of use
  4. Reuse enabling
  5. Better documentation quality production
  6. Higher individual productivity

Give wyz.code.rdoc package a try as it will
increase your R manual page creation
productivity. If you create packages, you have to provide manual pages
for each function you publish, you will thank yourself achieving this
task in less time, with better quality of result, in a possibly fully
automated and reproducible way.

Watch for next post on wyz.code.rdoc for more
advanced features to use in R documentation
generation.

  1. Business
    photo created by kues – freepik.com

To leave a comment for the author, please follow the link and comment on their blog: NEONIRA.

R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.



If you got this far, why not subscribe for updates from the site? Choose your flavor: e-mail, twitter, RSS, or facebook...

Comments are closed.

Search R-bloggers

Sponsors

Never miss an update!
Subscribe to R-bloggers to receive
e-mails with the latest R posts.
(You will not see this message again.)

Click here to close (This popup will not appear again)