Oxygenize R documentation

[eblondel]

To assess if the R documentation could be oxygenized using Roxygen or Roxygen2, where documentation will be added as comments within the R files, and Rd files generated automatically.

[Tungurahua]

I see the following pros and cons for using 'Roxygen2' for documentation:
Pro

• Code and documentation are stored in the same file thus a switch between files is not needed.
• Roxygen allows for automatic creation of 'NAMESPACE' and 'Collate' fields.
• in my opinion Roxygen sources are easier to read than plain .Rd files. However that's certainly a matter of general preference.
• Rstudio includes support (e.g tab-completion etc) for the fields available in .Rd files
• Roxygen code resides in an .rscript file. In RStudio this means that code examples can be executed while writing the documentation with the same shortcut keys used when coding.

Con

• automatic creation of NAMESPACEand collate might mean a loss of flexibility (though I don't see this at the moment
• Using an additional intermediate step (use Roxygen to create .Rd files could be an additional source for systematic error. However I think Roxygen2 is widely used and reasonably stable.
• automatic creation of .Rd files means that git staging area will get filled with .Rd files in the staging area while the change has been introduced only in the .r files. Solution might be to put the contents of the man folder into ignore.

[Tungurahua]

On R-bloggers Yihui Xie (knitRauthor) announces a package rd2roxygen that automatically converts Rd files to Roxygen. Might be worth a try if the move to Roxygen is to be taken.

The announcement has been released in 2010.

[eblondel]

Thanks for to pointing to this package.. i will investigate on it. Roxygen seems to have many benefits, but i've also seen criticisms. This needs more assessment, and see how and when to move forward.

[Tungurahua]

No worries. I didn't mean to push for roxygen in any way. As noted above Rd is the standard documentation format for R packages and roxygen - despite all convenience - is an additional linguistic layer that needs to be resolved to create the documentation. Or to put it simple: there might be bugs in the parser from roxygen to Rd. This alone is more than enough reason to be cautious. I think this issue is even raised somewhere in the roxygen vignettes where it's stated that Rd - though more difficult to handle - still has the greater flexibility.
I just ran across the post and wanted to note it down. This issue seemed to be a good place.