-
Notifications
You must be signed in to change notification settings - Fork 54
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Revise roxygen2 requirement in pkg_building chapter #792
Comments
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 |
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:
|
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).
What do you mean? The functions should be loaded not sourced? An usual workflow is to run
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. |
Sorry, ignore that. I have had the habit of doing
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:
The text was updated successfully, but these errors were encountered: