It can be clearer to propose specific changes, rather than describe the change in words.
Code can be included in comments via a markdown code chunk.
For example, this .Rd snippet proposes documentation for the vfont argument of ?text (cf. Bug 17791)
```
\item{vfont}{\code{NULL} for the current font family, or a character
vector of length 2 for \code{\link[grDevices]{Hershey}} vector fonts.
The first element of the vector selects a typeface and the second element
selects a style. Ignored if \code{labels} is an expression.}
```
Reviewing Documentation Patch
Text:
Are changes correct?
Is the updated text clearer?
Examples:
Do they work?
Are they worthwhile?
Formatting: is R documentation markup correct?
Add comment to confirm patch is fine, or suggest improvements.
Proposing updates in a comment
It can be clearer to propose specific changes, rather than describe the change in words.
Code can be included in comments via a markdown code chunk.
For example, this .Rd snippet proposes documentation for the vfont argument of ?text (cf. Bug 17791)
```
\item{vfont}{\code{NULL} for the current font family, or a character
vector of length 2 for \code{\link[grDevices]{Hershey}} vector fonts.
The first element of the vector selects a typeface and the second element
selects a style. Ignored if \code{labels} is an expression.}
```
Modifying/Creating a Patch
Patch files are created by modifying a copy of the R source code, which is version controlled with Subversion.
A few options:
Install Subversion, edit file locally, use svn diff to create a patch file
Local settings (e.g. indentation, EOL), can create noise.
The line numbers in the patch are off by 1 due to changes since the patch was created.
Create an updated patch
The file can be opened in VS code for further editing
$ code open src/library/base/man/c.Rd
After making changes create a new patch, e.g.
svn diff > patches/patch-c-rd-v2
The file can be downloaded from the codespace to attach with a comment on Bugzilla
Updated patch
Index: src/library/base/man/c.Rd
===================================================================
--- src/library/base/man/c.Rd (revision 85035)
+++ src/library/base/man/c.Rd (working copy)
@@ -43,8 +43,8 @@
\code{c} is sometimes used for its side effect of removing attributes
except names, for example to turn an \code{\link{array}} into a vector.
\code{as.vector} is a more intuitive way to do this, but also drops
- names. Note that methods other than the default are not required
- to do this (and they will almost certainly preserve a class attribute).
+ names. Note that \code{c} methods other than the default are not required
+ to strip attributes (and they will almost certainly preserve a class attribute).
This is a \link{primitive} function.
}
@@ -66,7 +66,7 @@
attribute-free vectors.
}
\examples{
-c(1,7:9)
+c(1, 7:9)
c(1:5, 10.5, "next")
## uses with a single argument to drop attributes
@@ -87,9 +87,8 @@
## but rather
c(ll, d = list(1:3)) # c() combining two lists
+## descend through lists:
c(list(A = c(B = 1)), recursive = TRUE)
-
-c(options(), recursive = TRUE)
c(list(A = c(B = 1, C = 2), B = c(E = 7)), recursive = TRUE)
}
\keyword{manip}
These are the changes that were made in the end by R Core member, Sebastian Meyer (view on GitHub mirror).
Code
Reviewing Code Bug Reports
Similar to reviewing documentation bugs, but more potential actions:
Add a reprex (minimal, reproducible example) if necessary
Analyse the bug
Identify the root cause
Identify the correct behaviour
Bug analysis is often the most time-consuming part
