During a lunch with Rob Hyndman and Earo Wang last week in Melbourne, I was surprised to know that there still existed packages that did not use roxygen to write the R documentation (my greatest sympathy to those poor authors), and I was also pleasantly surprised that Rob knew and actually used my Rd2roxgyen package to convert the documentation of his packages to roxygen.
After Earo heard about this, she immediately started working on her hts package. She was one of the most impressive R ladies I had ever met. With a Buffalo wing in her left hand, and the Z shell in the right hand, she almost got it done a few minutes after Rob and I talked briefly about Rd2roxygen.
I blogged about Rd2roxygen in 2010 and have almost forgotten it (that is why blogging is important). Today I just saw Joseph Stachelek tweeted about it. I’m happy that people still keep rediscovering it.
Without roxygen, I don’t think I could keep the momentum of working on more R packages. I was totally frustrated with the documentation of my first R package (animation), and almost wanted to give up. Then roxygen appeared, thanks to its original authors Peter Danenberg and Manuel Eugster, and I felt it was a life-saver. The main reasons for switching to roxygen for me were:
-
In-source documentation, and no going back and forth between
.Rand.Rd. -
Fewer backslashes. It should be well known now that I very much want to avoid reading any source files that contain LaTeX commands.
Over these years there have been a lot of improvements in the roxygen2 package. For example, originally roxygen was actually terribly slow, and it became much faster after Hadley joined the force (it was largely rewritten and released as another package roxygen2). Not long ago, roxygen2 started to support Markdown, too, which means the number of backslashes can be even smaller. Unless you a member of the R core team, I don’t see any reasons why you should still stay in the Rd world.
If you still have packages with Rd but not roxygen comments and want to try Rd2roxgyen, the most important thing you should know is that the Rd2roxygen conversion from Rd to roxygen is not meant to be perfect. Call Rd2roxygen::Rd2roxygen() once on your package source directory, and it is quite likely that there are things you need to tweak manually. Make sure that your package source is under version control, so when you roxygen2::roxygenize() the package, you can see the differences in Rd files. Of course, you also need to build and install the package, and read the help pages to see if there is anything wrong. This is not pleasant work, but fortunately it is a one-time thing. Once you have moved to the roxygen land, your life will be easier ever. And you are free to delete Rd2roxygen then.
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).