I must admit that I have been tired of maintaining my R packages for a long time, and the main reason is I feel really uncomfortable with writing R documentations (Rd). The required structure of an R package mainly includes two directories R and man – the former for the R source code (typically functions), and the latter for documentation. In the past I usually use package.skeleton() to generate a skeleton of the documentation and fill in the tags one by one. The main headache is to frequently switch between the two files and type the raw Rd commands such as \title{} and \description{}.
People told me all kinds of advantages of Emacs+ESS in the past few years, and I tried it for more than ten times, but often ended up with frustration (so I installed and removed Emacs repeatedly for several times). My last attempt a few months ago succeeded finally, and I realized how easy it was to document R functions in Emacs with roxygen. See the 1-minute video below:
In Emacs (with ESS), you just press C-c C-o to insert a documentation template as roxygen comments above your function, and the rest of things to do are to fill the @tags and update them when necessary. These inline comments will be converted to the real Rd files when we run R CMD roxygen your.package or roxygenize('your.package'). For details please read the vignette of the roxygen package. In all, roxygen makes the life of developers much easier. Then a natural problem comes:
What if I have already been stuck in the raw Rd files?
Since R 2.9.x, Duncan Murdoch announced a new way of parsing Rd files (mainly the function tools::parse_Rd()), which is quite useful for converting Rd files to other formats (e.g. Rd2txt(), Rd2latex(), …). This also brings us the possibility of converting Rd files to roxygen comments. I asked the question in R-help a few days ago, and Hadley pointed me to his code snippets on this conversion. I was fairly happy about them, so I sat down and spent one day on improving them. Finally I released this work as an R package Rd2roxygen on CRAN.
The main function that the developers may want to use is Rd2roxygen(): given a package root directory, this function can parse all the Rd files under the man directory, convert them into roxygen comments and update all the corresponding R scripts under the R directory. Most of the Rd tags are supported, but we may need some tiny adjustment by hand. Moreover, the function roxygen_and_build() can be of help for building packages. It tries to remove the unnecessary Rd files generated automatically by roxygen, replaces % with \% (because I believe it is very uncommon to write comments with % in Rd files; this replacement is optional, though), and builds the source package. Optionally it also installs or checks the package.
After I have done this package, I experimented on my animation package, and the converted package, when roxygenized, can pass R CMD check (I have moved the package to GitHub). This finally gives me new courage to actively maintain my old packages… My brain cannot deal with too many functions without seeing the documentation instantly.
This new package might have little bugs, of course. Please let me know if it does not work for you.
Donate
As a freelancer (currently working as a contractor) and a dad of three kids, I truly appreciate your donation to support my writing and open-source software development! Your contribution helps me cope with financial uncertainty better, so I can spend more time on producing high-quality content and software. You can make a donation through methods below.
-
Venmo:
@yihui_xie, or Zelle:xie@yihui.name -
Paypal
-
If you have a Paypal account, you can follow the link https://paypal.me/YihuiXie or find me on Paypal via my email
xie@yihui.name. Please choose the payment type as “Family and Friends” (instead of “Goods and Services”) to avoid extra fees. -
If you don’t have Paypal, you may donate through this link via your debit or credit card. Paypal will charge a fee on my side.
-
-
Other ways:
WeChat Pay (微信支付：谢益辉) Alipay (支付宝：谢益辉) 
When sending money, please be sure to add a note “gift” or “donation” if possible, so it won’t be treated as my taxable income but a genuine gift. Needless to say, donation is completely voluntary and I appreciate any amount you can give.
Please feel free to email me if you prefer a different way to give. Thank you very much!
I’ll give back a significant portion of the donations to the open-source community and charities. For the record, I received about $30,000 in total (before tax) in 2024-25, and gave back about $15,000 (after tax).