Document R Code

background-image: url(https://i.imgur.com/CVIZGyY.jpg)
background-position: top
background-size: 100%
class: inverse, shadow

body {
  font-family: 'Fira Sans','Droid Serif', 'Palatino Linotype', 'Book Antiqua', Palatino, 'Microsoft YaHei', 'Songti SC', serif;
}

a, a > code {
  color: #EC99C6;
  text-decoration: none;
}

strong {
  color: #E69F00;
}

em {
  color: #56B4E9;
  font-style: normal;
  font-weight: bold;
}

del {
  color: #E5E5E5;
  text-decoration: none;
  font-weight: bold;
}

.remark-code {
  font-family: 'IBM Plex Mono', 'Lucida Console', Monaco, monospace;
  font-size: 100%;
}

.remark-inline-code {
  font-family: 'Fira Sans', 'Lucida Console', Monaco, monospace;
  font-weight: 400;
  font-size: 100%;
}

.remark-code-line-highlighted {
  background-color: #CEE9FF;
  font-weight: 500;
}

.large { font-size: 130% }
.medium { font-size: 115% }
.small { font-size: 70% }

.remark-slide-content {
  color: #474747;
  font-weight: 300;
  font-weight: 300;
  padding: 1em 2em 1em 2em
}

h1 {
  color: #56B4E9;
  font-weight: 500;
}

h2 {
  font-weight: 500;
}

.remark-slide-number {
  font-size: 20px;
}

.title-slide .remark-slide-number {
  display: none;
}

.inverse.title-slide {
  background-size: cover;
  color: #EDEEEF;
}

.inverse.title-slide h1  {
  color: #E69F00;
  font-size: 72px;
  text-shadow: none;
  text-align: left;
  vertical-align: bottom;
}
.inverse.title-slide h2  {
  color: #56B4E9;
  text-shadow: none;
  font-size: 48px;
  text-align: left;
  font-weight: bold;
}
.inverse.title-slide h3  {
  color: #EDEEEF;
  text-shadow: none;
  font-size: 36px;
  text-align: left;
  margin-bottom: 10px;
}

.inverse.title-slide h4  {
  color: #EDEEEF;
  text-shadow: none;
  font-size: 24px;
  text-align: left;
  margin-bottom: 10px;
}

.inverse {
  background-size: cover;
  background-color: #23373B;
  color: #EDEEEF;
  font-weight: bold;
  text-shadow: none;
}

.inverse-ns {
  background-size: cover;
  background-color: #23373B;
  color: #EDEEEF;
  text-shadow: none;
  font-weight: bold;
}

.takeaways {
  padding-top: 80px;
}

.inverse h2, .inverse h3  {
  color: #EDEEEF;
  font-weight: 500;
}

.inverse del {
  color: #6C7B7F;
}

.shadow { text-shadow: 0 0 20px rgba(51,51,51,0.35) }

img {
  display: block;
  margin-left: auto;
  margin-right: auto;
}

ul {
  font-size: 48px;
  list-style-type: none;
  text-align: left;
  font-weight: 500;
  padding-top: 40px;
}

ul li {
  padding-bottom: 40px;
}

ol {
  counter-reset: my-counter;
  list-style: none;
  padding-left: 40px;
  font-size: 45px;
  font-weight: bold;
  text-align: left;
}

ol li {
  counter-increment: my-counter;
  padding-left: 40px;
  position: relative;
  font-size: 45px;
  margin: 20px 0;
  display: block;
  margin-block-start: 0.83em;
  margin-block-end: 0.83em;
  margin-inline-start: 0;
  margin-inline-end: 0;
}

ol li::before {
  content: counter(my-counter);
  color: #fff;
  font-size: 40px;
  font-weight: bold;
  position: absolute;
  left: -25px;
  line-height: 50px;
  width: 50px;
  height: 50px;
  top: 0;
  background: #56B4E9;
  border-radius: 50%;
  text-align: center;
}</style>

# My Organization's First R package
## Document R Code
## `rstudio::conf(2020L)`

---

---

# ?mean

---

background-image: url(http://hexb.in/hexagons/roxygen2.png)
background-position: 90% 10%

## roxygen2: In-Line Documentation for R

---

background-image: url(http://hexb.in/hexagons/roxygen2.png)
background-position: 90% 10%

## roxygen2: In-Line Documentation for R

background-image: url(http://hexb.in/hexagons/roxygen2.png)
background-position: 90% 10%

## roxygen2: In-Line Documentation for R

## render with **`document()`**
]

---

# Insert roxygen skeleton

## **`Code > Insert Roxygen Skeleton`**

---

# Insert roxygen skeleton

## ~~`Code > Insert Roxygen Skeleton`~~
## **Ctrl/Cmd + Shift + Alt/Opt + R**

---

---

---

---

---

---

---

---

---

---

---

# Write roxygen, run `document()`

---

# Write roxygen, run `document()`

```r
theme_mako <- function(base_size = 14) {
  ggplot2::theme_dark(base_size = base_size) + 
    ggplot2::theme(
      panel.background = ggplot2::element_rect(fill = "#0D98BA")
    )
}
```

---

# Write roxygen, run `document()`

```r
#' A dark theme with a mako-like background
#'
#' @param base_size base font size
#'
#' @return a ggplot2 theme
#' @export
#'
#' @examples
#'
#' ggplot2::quickplot(iris$Sepal.Length) + theme_mako()
#'
theme_mako <- function(base_size = 14) {
  ggplot2::theme_dark(base_size = base_size) + 
    ggplot2::theme(
      panel.background = ggplot2::element_rect(fill = "#0D98BA")
    )
}
```

---

---

## `man/theme_mako.Rd`

```r
*## % Generated by roxygen2: do not edit by hand
*## % Please edit documentation in R/themes.R
## \name{theme_mako}
## \alias{theme_mako}
## \title{A dark theme with a mako-like background}
## \usage{
## theme_mako(base_size = 14)
## }
## \arguments{
## \item{base_size}{base font size}
## }
## \value{
## a ggplot2 theme
## }
## \description{
## A dark theme with a mako-like background
## }
## \examples{
## 
## ggplot2::quickplot(iris$Sepal.Length) + theme_mako()
## 
## }
```
]

---

## ?theme_mako

---

# Syntax

## LaTeX like. See more at https://r-pkgs.org/man.html

## `use_roxygen_md()` lets you write in Markdown. See more at https://roxygen2.r-lib.org/articles/rd-formatting.html

---

## Your Turn 1

#### Open the NAMESPACE file. What do you see?
#### Let's add documentation. Run `use_roxygen_md()`
#### Open `r/themes.R`. Insert a roxygen skeleton for `theme_avalanche()`.
#### Change the title to "AVALANCHE ggplot2 themes"
#### Hit Enter/Return twice after the title.  Make sure the new lines start with `#'`. Add this text: "Minimalistic ggplot themes for use on AVALANCHE reports."
#### Run `document()` or press `Ctrl/Cmd + Shift + D`. Read the help page for your function with `?theme_avalanche`.
#### Finally, look at the NAMESPACE file again. What changed?

---

## Your Turn 1

```r
exportPattern("^[^\\.]")
```
---

## Your Turn 1

```r
*#' AVALANCHE ggplot2 themes
#' 
*#' Minimalistic ggplot themes for use on AVALANCHE reports.
#'
#' @param base_size 
#' @param ... 
#'
#' @return
#' @export
#'
#' @examples
theme_avalanche <- function(base_size = 14, ...) {
  ggplot2::theme_minimal(base_size = base_size, ...) +
    ggplot2::theme(panel.grid.minor = ggplot2::element_blank())
}
```

---

## Your Turn 1

```r
# Generated by roxygen2: do not edit by hand

export("%>%")
export(db_con)
export(get_resident_data)
export(theme_avalanche)
export(theme_avalanche_h)
export(theme_avalanche_v)
import(data.table)
importFrom(magrittr,"%>%")
```

---

# Argument descriptions

```r
#' [other roxygen code]
*#' @param x The name of a database to retrieve
get_data <- function(x) {
  # code to get data
}
```

---

# Argument descriptions: @inheritParams

```r
#' [other roxygen code]
#' @param x The name of a database to retrieve
get_data <- function(x) {
  # code to get data
}

#' [other roxygen code]
*filter_table <- function(x) {
* tbl <- get_data(x)
  # code to filter data
}
```

---

# Argument descriptions: @inheritParams

```r
#' [other roxygen code]
#' @param x The name of a database to retrieve
get_data <- function(x) {
  # code to get data
}

#' [other roxygen code]
*#' @inheritParams get_data
filter_table <- function(x) {
  tbl <- get_data(x)
  # code to filter data
}
```

---

# Examples

## Examples can be any kind of R code

```r
#' [other roxygen code]
*#' @examples
*#'
*#' library(dplyr)
*#' get_data("daily_actice_users") %>%
*#'   filter(date == lubridate::today())
get_data <- function(x) {
  # code to get data
}
```

---

# Examples

## ~~Examples can be any kind of R code~~

```r
#' [other roxygen code]
#' @examples 
#' 
*#' library(dplyr)
#' get_data("daily_actice_users") %>% 
*#'   filter(date == lubridate::today())
get_data <- function(x) {
  # code to get data
}
```

## **But any packages used need to be imported or suggested!**

---

# Examples

## If you don't want to run examples, wrap them in `dontrun{}` or `donttest{}`

```r
#' [other roxygen code]
#' @examples 
#'
*#' dontrun{
*#'   get_data("daily_active_users")
*#' }
get_data <- function(x) {
  # code to get data
}
```

---

## Your Turn 2

### Let's keep working on the documentation for `theme_avalanche()`:
#### Remove `@param base_size` and replace it with: @inheritParams ggplot2::theme_minimal
#### For `@param ...`, add: Additional arguments passed to [ggplot2::theme_minimal()]
#### For `@return`, add: a ggplot theme.
#### For `@examples`, add two line breaks (make sure the new lines have roxygen comments!). Add this code: `ggplot2::qplot(iris$Sepal.Length) + theme_avalanche()`
#### Rebuild the documentation and check the help page.

---

## Your Turn 2

```r
#' AVALANCHE ggplot2 themes
#'
#' Minimalistic ggplot themes for use on AVALANCHE reports.
#'
*#' @inheritParams ggplot2::theme_minimal
*#' @param ... Additional arguments passed to [ggplot2::theme_minimal()]
#'
*#' @return a ggplot theme.
#' @export
#'
#' @examples
#'
*#' ggplot2::qplot(iris$Sepal.Length) + theme_avalanche()
#'
theme_avalanche <- function(base_size = 14, ...) {
  ggplot2::theme_minimal(base_size = base_size, ...) +
    ggplot2::theme(panel.grid.minor = ggplot2::element_blank())
}
```

---

---

# [Quoth Jenny Bryan](https://github.com/jennybc/code-smells-and-feels):

1. Use functions.
2. A few little functions >> a monster function
3. Small well-named helper >> commented code

---

## Helper functions

```r
plot_daus <- function(daily_users) {
  daily_users <- daily_users %>%
    dplyr::mutate(date = as.Date(time)) %>%
    dplyr::group_by(date)
    dplyr::select(user_id) %>%
    dplyr::distinct() %>%
    dplyr::summarize(n = dplyr::n()) 
  
  ggplot2::ggplot(ggplot2::aes(daily_users, x, n)) + 
    ggplot2::geom_col()
}
```

---

## Helper functions

```r
plot_daus <- function(daily_users) {
* daily_users <- count_daus(daily_users)
  
  ggplot2::ggplot(ggplot2::aes(daily_users, x, n)) + 
    ggplot2::geom_col()
}

*count_daus <- function(daily_users) {
  daily_users %>%
    dplyr::mutate(date = as.Date(time)) %>%
    dplyr::group_by(date)
    dplyr::select(user_id) %>%
    dplyr::distinct() %>%
    dplyr::summarize(n = dplyr::n()) 
}
```

---

## Show of Hands

## Which of these functions will be added to NAMESPACE?

```r
#' Plot daily active users
#' 
#' @param ...
#' @export 
plot_daus <- function(...) {
  # ... code to plot daily active users
}

#' Count daily active users
#' 
#' @param ...
count_daus <- function(...) {
  # ... code to count daily active users
}
```

---

## Show of Hands

## Which of these functions will be added to NAMESPACE?

```r
#' Plot daily active users
#' 
#' @param ...
*#' @export
plot_daus <- function(...) {
  # ... code to plot daily active users
}

#' Count daily active users
#' 
#' @param ...
count_daus <- function(...) {
  # ... code to count daily active users
}
```

---

## Exported functions vs internal functions

## **`@export`** = **`shinRa::plot_daus()`**

## *`library(shinRa)`*
## *`plot_daus()`* ✔️

---

## Exported functions vs internal functions

## **NO `@export`** = **`shinRa:::count_daus()`**

## *`library(shinRa)`*
## *`count_daus()`* 🤔🤔🤔🤔🤔🤔  
---

# Strategies for documenting helper functions:

1. Don't document them 🤷
2. @keyword internal
3. @nomd

---

# Joining documentation

```r
#' [other roxygen code]
#' @param x The name of a database to retrieve 
*get_data <- function(x) {
  # code to get data
}

#' [other roxygen code]
#' @param x @inheritParam get_data 
*filter_table <- function(x) {
  tbl <- get_data(x)
  # code to filter data
}
```

---

# Joining documentation

```r
#' [other roxygen code]
#' @param x The name of a database to retrieve 
get_data <- function(x) { 
  # code to get data
}

*#' @rdname get_data
*#' @export
filter_table <- function(x) { 
  tbl <- get_data(x)
  # code to filter data
}
```

---

# Joining documentation

```r
#' [other roxygen code]
#' @param x The name of a database to retrieve 
*#' @name data_helpers
*NULL

*#' @rdname data_helpers
#' @export 
get_data <- function(x) { 
  # code to get data
}

*#' @rdname data_helpers
#' @export 
filter_table <- function(x) { 
  tbl <- get_data(x)
  # code to filter data
}
```

---

# Joining documentation

```r
#' [other roxygen code]
#' @param x The name of a database to retrieve 
#' @name data_helpers 
NULL

#' @rdname data_helpers 
*#' @export
get_data <- function(x) { 
  # code to get data
}

#' @rdname data_helpers 
*#' @export
filter_table <- function(x) { 
  tbl <- get_data(x)
  # code to filter data
}
```

---

## Your Turn 3

#### In `R/themes.R`, join the documentation of `theme_avalanche_h()` and `theme_avalanche_v()` to `theme_avalanche()` by replacing the roxygen code for the first two functions with "#' @rdname theme_avalanche". 
#### Make sure both functions still have an export tag, as well!
#### Re-render the documentation and read the help page for `?theme_avalanche_h()`

---

## Your Turn 3

```r
*#' @rdname theme_avalanche
*#' @export
theme_avalanche_h <- function(base_size = 14, ...) {
  ggplot2::theme_minimal(base_size = base_size, ...) +
    ggplot2::theme(
      panel.grid.minor = ggplot2::element_blank(),
      panel.grid.major.x = ggplot2::element_blank()
    )
}

*#' @rdname theme_avalanche
*#' @export
theme_avalanche_v <- function(base_size = 14, ...) {
  ggplot2::theme_minimal(base_size = base_size, ...) +
    ggplot2::theme(
      panel.grid.minor = ggplot2::element_blank(),
      panel.grid.major.y = ggplot2::element_blank()
    )
}
```

---

# Package documentation

## `use_package_doc()`

```
## ✔ Setting active project to '/private/var/folders/03/9x7925g54mncswxx06wpkxl00000gn/T/Rtmp7tPP...
## ✔ Writing 'R/shinRa-package.R'```

---

## `help("tidyr")`

---

background-image: url(https://raw.githubusercontent.com/r-lib/pkgdown/master/man/figures/logo.png)
background-position: 90% 10%

# pkgdown

---

background-image: url(https://raw.githubusercontent.com/r-lib/pkgdown/master/man/figures/logo.png)
background-position: 90% 10%

# pkgdown

---

background-image: url(http://hexb.in/hexagons/roxygen2.png)
background-position: 90% 10%

## https://roxygen2.r-lib.org/
## There are a lot more documentation tricks.
## Read the vignettes!
]