Choose wisely your Rdoc production strategy!

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

Last post ‘Still hand-crafting your Rdoc
files?’
introduced package
wyz.code.rdoc to produce
R documentation file in a possibly fully
automated way. Let’s see today, which production strategy will offer you
the most powerful and productive way to produce those
R documentation files.

Available weapons

Remember that package wyz.code.rdoc aims to
generate documentation from code, by code. It provides many weapons
to do so, and let’s review here the most important ones

  1. The ProcessingContext class allows you to
    define two type of actions to modify documentation content

    1. An extraneous action to add on-demand
      extraneous sections into generated documentation
    2. A post processing action to
      replace/adapt documentation content as you desire
  2. The shortcuts class allows you to reuse most
    common presentation content in your documentation
  3. The beautify class allows you to beautify
    the presentation of your content

To know more about options, signatures, and arguments, use

help(package = 'wyz.code.rdoc')
vignette(package = 'wyz.code.rdoc')

Qualify your need

Prior executing any R documentation file
production, you have to decide your playground. Answering following
questions is helpful to do so

Should the documentation file be regenerated on demand?
If you
want to have documentation along your code while creating the package
the answer is probably positive. If you want to defer documentation
production to the last time prior package delivery, the answer is
probably no. In both cases, go for fully automated
R documentation file production. In first case,
avoid any hand-crafting produced files, in second case, you are free to
do so.

Will you spend time to polish manually produced files?
While
you should generally avoid hand touch-ups, sometimes a short and
efficient edition of the file can be preferred to a longer and possibly
tricky processing to get to the desired result.

For example, when checking a R package, there
are checks related to the length of documentation lines. Fixing this
manually or by a post processing action is up
to your choice. But time required in each way, could possibly be very
different. If you seek for immediate high productivity, choose wisely.
There is no way to decide out of context which tactic is the best for
your case.

Do your package code have a lot of identical function parameter
names?

If this is the case, then structuring reusable parts will
allow you to earn a lot of time while generating all documentations of
your R package, while ensuring greater
consistency. Package wyz.code.rdoc is very
helpful in such case.

Industrial way to produce documentation

You have to know that wyz.code.rdoc manual page
production depends upon

  1. the kind of documentation you want to generate:
  2. your R code flavor

Documentation kinds are standard, and relate to destination of the
manual page: function,
class, package, or
data. When you produce one of those manual page
kinds, you have to comply with a different set of requirements in
section presence, section content, and very probably also on section
presentation.

Your R code flavor also impacts the volume of
work you will have to achieve to get a correctly filled in manual page,
well formatted, consistent with other manual pages from your package,
and easy to read. Either your code is standard R
code
or it is offensive programming R
code
.

From standard R code to manual page

Manual pages generation is partial, and you will
have to provide extraneous and
post processing actions to generate their
content. If you don’t do so, each generated manual page remains
incomplete and won’t pass package tests. That’s why, documentation
completion is required.

Considering a function or
class manual page, you have to provide content
for sections examples and
description, at the very least. You also
probably need to provide content for section
details and values.

Considering a package manual page, you have to
provide content for sections description and
probably content for section details.

Considering a data manual page, you have to
provide content, at least for sections format
and source.

From offensive programming R code to manual page

Using offensive programming R code eases
greatly manual pages production. As, this is based on argument semantic
naming, many fields content are generated from code without extra burden
for you, thus allowing to fulfill documentation section requirements
without any extraneous information.

  1. parameter description is inferred from semantic parameter name, and
    generally do not require any change. As this applies to each
    argument of each function of your package, such a feature is a great
    benefit and allows to earn a lot of time,
  2. description is inferred from class and function offensive
    programming naming scheme. If you respected its
    strict mode, expect produced content to be
    sharp and finalized no modification
    required
    . If you don’t, you will probably need to perfect its
    content, by a post processing action or some
    hand touch-ups.

Manual pages generation is full except for
data where you do have to provide content, as
described above. In all other cases, generated manual pages are complete
and ready for human preview and review.

Choose the best strategy according to your case

First, whatever your R code flavor, a good
documentation requires examples. That’s probably
the most important part of your documentation, polish it. I already
shown on previous post, how easy it is to declare such information, to
generate a manual page.

Working under standard R code, supply
extraneous and post
processing
information in
ProductionContext definition, prior generation,
in order to comply with requirements related to the the kind of
generated manual page. Doing so, will allow production of immediately
compliant manual pages.

Using offensive programming R code, just think
to supply extraneous information in
ProductionContext definition, prior generation,
in order to comply with requirements related to the the kind of
generated manual page.

Next post

We have seen that wyz.code.rdoc package allows
fully automated and reproducible R manual page
production. It helps enforcing the required/desired level of consistency
for your R documentation files in your
packages.

Not mentioned previously but quite obvious, using
wyz.code.rdoc eases incremental documentation
generation. When creating a package, the workflow is generally create
and debug code, then create test, then create documentation.

With wyz.code.rdoc, you can adopt a
domain-driven approach that is, create domain examples, implement and
debug code, generate documentation based on domain examples, create
tests reusing in priority domain examples. That way, the code generation
process is really incremental and domain-driven.

On small size packages, this does not make a significant difference, but
and large size packages, this eases a lot the production, especially
when many programmers are working on the same package. Documentation can
be generated automatically or on-demand at the same time the code is
delivered, thus increasing visibility and immediate reuse.

If you seek for higher collaboration and shorter tunnel effect, going
for incremental deliveries of package functionalities is powerful and
wyz.code.rdoc automates documentation
production activities to sustain your productivity.

Next post will provide wyz.code.rdoc tips and
tricks worth to know to get productive documentation generation.

[1] Business
photo created by yanalya – 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.

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)