Commit 12d06fa4 authored by Jason Rigby's avatar Jason Rigby
Browse files

add more documentation

parent 804129a5
......@@ -24,6 +24,28 @@ aspreeConsent <- aspreeDb("ASPREE Data Snapshot") %>% getXTConsent()
Recommended reading: [the devtools cheatsheet](https://www.rstudio.com/wp-content/uploads/2015/03/devtools-cheatsheet.pdf)
## Quick-start: Eight steps to writing a new function
1. Create or open an appropriate .R file inside the [R subdirectory](R)
2. Write your code, but don't include any `library` or `require` statements
3. Write the documentation (in roxygen format) above the function, adding `@import` or `@importFrom` to the roxygen code for any library that you would otherwise load with `library`. [Note that best practise is to be explicit](http://kbroman.org/pkg_primer/pages/depends.html), using the `::` operator to select the function directly from any package. In other words, try to avoid importing entire packages altogether.
4. Add `@export` to the documentation if this function is intended to be exposed to the end-user
5. Declare any additional dependencies (things that would need to be installed using `install.packages()`) by running `devtools::use_package("package-name")` for each required package, which will automatically update the `DESCRIPTION` file
6. (Try to) [write tests](tests/testthat)
7. Run `devtools::document()` to update `NAMESPACE` and the files inside `man`
8. Commit all the changes to git, and merge to the main repository
Regarding point (3), an example comparing the `library` statement with calling functions explicity, consider the following:
```
# Loading the libraries
library(DBI)
library(odbc)
con <- dbConnection(odbc(), "My Database")
# Explicitly calling each function
con <- DBI::dbConnection(odbc::odbc(), "My Database")
```
In the latter case, the programmer has no confusion about where each function originated, whereas the former relies upon the programmer having prior knowledge about the structure of the `DBI` and `odbc` packages.
## Dependencies
Package dependencies must be declared in the [DESCRIPTION](DESCRIPTION) file. Use the `devtools::use_package()` function to add these automatically.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment