Closed vincentvanhees closed 6 months ago
Thanks for your reflections @vincentvanhees! I appreciate the measured input. But I think we are unlikely to make this change.
One of our bigger considerations is that packages are easier for reviewers to review and for new contributors and maintainers to participate in development. As such, we put more weight on development practices that are fairly ubiquitous, expected by most developers, and have a lot of supported tooling. We impose more homogeneity than if our standards were based only on standalone quality. Popularity is of course not the only criterion: there is considerable value in keeping documentation and code in the same location, from both a maintainer and reviewer perspective. But having a common standard is the most important consideration here, and common practice is heavily in favor of using roxygen. In fact, for our statistical packages we've built our (required) code annotation tooling on top of Roxygen.
Also thanks from me @vincentvanhees for your insightful consideration. I do nevertheless concur with Noam's insights, and add one further point that we also have a centralised document building service which is greatly simplified by our Roxygen requirement. I personally think the current wording is sufficiently clear, in stating that "Roxygen ... automatically compiles .Rd
files," but as always we are open to pull requests which aim to improve our wording or descriptions. I'll close this for now, but please feel free to suggest any minor changes via a pull request if you like. Thanks again for your input.
Ok, I understand. In that case I would advise to make the phrasing a bit more diplomatic towards those who have used Rd files and are at the point of having to transition to roxygen. I think it is easier to get them on board by providing valid arguments and refraining from wording that could be perceived as opinionated. I would then suggest the following changes:
Line 218: "roxygen2 is an R package that automatically compiles .Rd
files to your man
folder in your package from simple tags written above each function" because the user still needs to run the command roxygenise() each time documentation is changed and the tags are not any more simple than the fields in a Rd file. If you disagree then it would be good to include a reference to a description of what makes the tags more simple than Rd fields.
Line 222: "If you were writing Rd by hand, .... " replace by "If you were writing Rd directly without Roxygen, ... ". This would better reflect that documentation always needs to be written by hand regardless of whether it is a Roxygen tag or field in the Rd files.
Thanks a lot @vincentvanhees! I am preparing a PR with your wording changes (and a pointer to roxygen2's Markdown support, as reading your comment made me realize this could be viewed as an upside).
the developer needs to remove all sourced package functions, if any, and then run the roxygenise() command.
What do you mean? The functions should be loaded not sourced? An usual workflow is to run devtools::document()
.
More documentation means more scrolling to the code.
However there are other ways, depending on the chosen development environment, to directly get to a function of interest. I for instance use RStudio IDE and use both the "Go to file/function" search bar, and the table of contents on the right of my scripts. So I only scroll within functions.
What do you mean? The functions should be loaded not sourced?
Sorry, ignore that. I have had the habit of doing for (i in functionpaths) source(i)
when debugging, but now realise that devtools::load_all(".")
is easier and wouldn't clash with roxygenise :)
However there are other ways, depending on the chosen development environment, to directly get to a function of interest. I for instance use RStudio IDE and use both the "Go to file/function" search bar, and the table of contents on the right of my scripts. So I only scroll within functions.
My bad, I think it is time I followed some RStudio tutorial again as I did not know about that trick yet.
Thanks for writing the guide, it is an amazing resource.
The pkg_building chapter requests all submissions to use roxygen2. I have written R packages both with and without roxygen2, and see strengths and weaknesses in both approaches. Further down I have typed out my elaborate reflections, but in summary the changes to the guide I would like to propose are:
I am happy to prepare a PR for this, but first wanted to check that you are open to such a change. Also, I hope this does not read like a rant about Roxygen2, I sincerely respect both approaches and feel that the ultimate choice should be left up to the user as the best choice may be context specific.
Specific reflections: