R - Choose wisely your Rdoc production strategy!
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
- The ProcessingContext class allows you to
define two type of actions to modify documentation content
- An extraneous action to add on-demand extraneous sections into generated documentation
- A post processing action to replace/adapt documentation content as you desire
- The shortcuts class allows you to reuse most common presentation content in your documentation
- 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
- the kind of documentation you want to generate:
- 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.
- 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,
- 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.