forked from COMBINE-Australia/r-pkg-dev
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy path05-documentation.Rmd
241 lines (207 loc) · 6.99 KB
/
05-documentation.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
# Documenting functions
The output of our check tells us that we are missing documentation for the
`make_shades` function. Writing this kind of documentation is another part of
package development that has been made much easier by modern packages, in this
case one called **roxygen2**. R help files use a complicated syntax similar to
LaTeX that can be easy to mess up. Instead of writing this all ourselves
using Roxygen lets us just write some special comments at the start of each
function. This has the extra advantage of keeping the documentation with the
code which make it easier to keep it up to date.
## Adding documentation
To insert a documentation skeleton in RStudio click inside the `make_shades`
function then open the _Code_ menu and select _Insert Roxygen skeleton_ or use
**Ctrl + Alt + Shift + R**. The inserted code looks like this:
```{r}
#' Title
#'
#' @param colour
#' @param n
#' @param lighter
#'
#' @return
#' @export
#'
#' @examples
```
Roxygen comments all start with `#'`. The first line is the title of the
function then there is a blank line. Following that there can be a paragraph
giving a more detailed description of the function. Let's fill those in to
start with.
```{r}
#' Make shades
#'
#' Given a colour make n lighter or darker shades
#'
#' @param colour
#' @param n
#' @param lighter
#'
#' @return
#' @export
#'
#' @examples
```
The next section describes the parameters (or arguments) for the function marked
by the `@param` field. RStudio has helpfully filled in names of these for us
but we need to provide a description.
```{r}
#' Make shades
#'
#' Given a colour make n lighter or darker shades
#'
#' @param colour The colour to make shades of
#' @param n The number of shades to make
#' @param lighter Whether to make lighter (TRUE) or darker (FALSE) shades
#'
#' @return
#' @export
#'
#' @examples
```
The next field is `@return`. This is where we describe what the function
returns. This is usually fairly short but you should provide enough detail to
make sure that the user knows what they are getting back.
```{r}
#' Make shades
#'
#' Given a colour make n lighter or darker shades
#'
#' @param colour The colour to make shades of
#' @param n The number of shades to make
#' @param lighter Whether to make lighter (TRUE) or darker (FALSE) shades
#'
#' @return A vector of n colour hex codes
#' @export
#'
#' @examples
```
After `@return` we have `@export`. This field is a bit different because
it doesn't add documentation to the help file, instead it modifies the
`NAMESPACE` file. Adding `@export` tells Roxygen that this is a function that
we want to be available to the user. When we build the documentation Roxygen
will then add the correct information to the `NAMESPACE` file. If we had an
internal function that wasn't meant to be used by the user we would leave out
`@export`.
The last field in the skeleton is `@examples`. This is where we put some
short examples showing how the function can be used. These will be placed in
the help file and can be run using `example("function")`. Let's add a couple
of examples. If you want to add a comment to an example you need to add
another `#`.
```{r}
#' Make shades
#'
#' Given a colour make n lighter or darker shades
#'
#' @param colour The colour to make shades of
#' @param n The number of shades to make
#' @param lighter Whether to make lighter (TRUE) or darker (FALSE) shades
#'
#' @return A vector of n colour hex codes
#' @export
#'
#' @examples
#' # Five lighter shades
#' make_shades("goldenrod", 5)
#' # Five darker shades
#' make_shades("goldenrod", 5, lighter = FALSE)
```
> **Other fields**
>
> In this example we only fill in the fields in the skeleton but there are many
> other useful fields. For example `@author` (specify the function author),
> `@references` (any associated references) and `@seealso` (links to related
> functions).
## Building documentation
Now we can build our documentation using **devtools**.
```{r}
devtools::document()
```
```{}
Updating mypkg documentation
Updating roxygen version in C:\Users\USER\Desktop\mypkg/DESCRIPTION
Writing NAMESPACE
Loading mypkg
Writing NAMESPACE
Writing make_shades.Rd
```
The output shows us that **devtools** has done a few things. Firstly it has
set the version of **roxygen2** we are using in the `DESCRIPTION` file by
adding this line:
```{}
RoxygenNote: 6.1.1
```
Next it has updated the `NAMESPACE` file. If you open it you will see:
```{r}
# Generated by roxygen2: do not edit by hand
export(make_shades)
```
Which tells us that the `make_shades` function is exported.
The last thing it has done is create a new file called `make_shades.Rd` in the
`man/` directory (which will be created if it doesn't exist). The `.Rd`
extension stands for "R documentation" and this is what is turned into a help
file when the package is installed. Open the file and see what it looks like.
```{}
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/colours.R
\name{make_shades}
\alias{make_shades}
\title{Make shades}
\usage{
make_shades(colour, n, lighter = TRUE)
}
\arguments{
\item{colour}{The colour to make shades of}
\item{n}{The number of shades to make}
\item{lighter}{Whether to make lighter (TRUE) or darker (FALSE) shades}
}
\value{
A vector of n colour hex codes
}
\description{
Given a colour make n lighter or darker shades
}
\examples{
# Five lighter shades
make_shades("goldenrod", 5)
# Five darker shades
make_shades("goldenrod", 5, lighter = FALSE)
}
```
Hopefully you can see why we want to avoid writing this manually! This is only
a simple function but already the help file is quite complicated with lots of
braces. To see what the rendered documentation looks like just run
`?make_shades`.
## Formatting documentation
The rendered output already looks pretty good but we might want to add some
extra formatting to it to make it a bit clearer. As we have seen above there
is a special syntax for different kinds of formatting. For example we can mark
code in the documentation using `\code{}`.
```{r}
#' Make shades
#'
#' Given a colour make \code{n} lighter or darker shades
#'
#' @param colour The colour to make shades of
#' @param n The number of shades to make
#' @param lighter Whether to make lighter (\code{TRUE}) or darker (\code{FALSE})
#' shades
#'
#' @return A vector of \code{n} colour hex codes
#' @export
#'
#' @examples
#' # Five lighter shades
#' make_shades("goldenrod", 5)
#' # Five darker shades
#' make_shades("goldenrod", 5, lighter = FALSE)
```
Run `devtools::document()` again and see what has changed in the rendered file.
There are many other kinds of formatting we could use, for example: `\code{}`,
`\eqn{}`, `\emph{}`, `\strong{}`, `\itemize{}`, `\enumerate{}`, `\link{}`,
`\link[]{}`, `\url{}`, `\href{}{}`, `\email{}`.
> **Using Markdown**
>
> If you are familiar with Markdown you may prefer to use it for writing
> documentation. Luckily Roxygen has a Markdown mode that can be activated using
> `usethis::use_roxygen_md()`. See the Roxygen Markdown vignette for more
> details https://cran.r-project.org/web/packages/roxygen2/vignettes/markdown.html.