Other sites

Still hand-crafting your Rdoc files?

[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.

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 packagewyz.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 ofR code to generate anyR 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 followingdummyR function
that resides in a package namedlambdaPackage.

Generation process overview

set a processing context, expressing sections to add, and any
required post processing actions to get fully documented manual
page,

generate your R manual page using functionproduceManualPage

Get immediate result of compliance againstR documentation checks

Notice some important points

Here, generated manual page

is produced for a package and package name matters in such
context,

took into consideration your content and format customizations,

has used the 3 examples you provided,

patched at your demand the content of function arguments,

removed at your demand authorship from the output

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.

Produced manual page has gone through standardR 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

Nearly full coverage of the previously exposedR process

High flexibility customization

Ease of use

Reuse enabling

Better documentation quality production

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.