How to inherit roxygen documentation from data

Question

I have read about roxygen2 inheritance with datasets and documenting data added to an R package from the documentation and from other SO questions. However, I cannot figure out how to inherit documentation between datasets.

I have one data set, data1, with 3 columns and 100 rows. I have another data set, data2, with 5 columns and 75 rows. data2 includes all columns in data1, with a couple extras. Here is an example of what the data look like:

data1
##>  A tibble: 100 × 3
#>   name  school grade
#>   <chr> <chr>  <chr>
#> 1 Joe   EHS    A
#> 2 Amy   EHS    B
#> 3 Sara  WHS    A
#etc...

data2
##>  A tibble: 75 × 5
#>   name  school grade gender sport     
#>   <chr> <chr>  <chr> <chr>  <chr>
#> 1 Joe   EHS    A     M      basketball
#> 2 Amy   EHS    B     F      swimming
#> 3 Jack  EHS    C     M      football
#etc...

Here is how I have data1 documented:

#' School Enrollment Data
#' 
#' School enrollment data for the 2018-2019 school year. 
#' 
#' @format A tibble with 100 rows and 3 columns:
#' \describe{
#'    \item{name}{Name of the student}
#'    \item{school}{Name of the school}
#'    \item{grade}{Grade of the student}
#' }
#' @source xyz
"data1"

How can I document data2 using inheritance? I would like to create documentation without having to copy-paste from the documentation of data1.

Here's what I have so far:

#' School Enrollment Detail Data
#' 
#' School enrollment detail data for the 2018-2019 school year.
#' 
#' ### Inheritance here?
#' 
#' @format A tibble with 75 rows and 5 columns:
#' \describe{
#'    \item{gender}{Gender of the student}
#'    \item{sport}{Sport of the student}
#' }
#' @source xyz and abc
"data2"

`@inheritSection data1 format` See https://cran.r-project.org/web/packages/roxygen2/vignettes/reuse.html — user12256545, Jun 13 '23 at 22:06
Thanks for the suggestion - "format" is not identified as a section by `roxygen2`, so this produces an error — mfg3z0, Jun 13 '23 at 22:11

score 0 · Answer 1 · answered Jun 13 '23 at 22:48

I found a solution that works well! I can put the fields from data1 in a @section and then use @inheritSection to include this in the data2 documention.

The code looks like:

#' School Enrollment Data
#' 
#' School enrollment data for the 2018-2019 school year. 
#' 
#' @format A tibble with 100 rows and 3 columns
#'
#' @section Data1 Fields:
#'   \describe{
#'      \item{name}{Name of the student}
#'      \item{school}{Name of the school}
#'      \item{grade}{Grade of the student}
#'   }
#'
#' @source xyz
#'
#' @docType data
"data1"

#' School Enrollment Detail Data
#' 
#' School enrollment detail data for the 2018-2019 school year.
#' 
#' @format A tibble with 75 rows and 5 columns
#'
#' @section Data2 Unique Fields:
#'   \describe{
#'      \item{gender}{Gender of the student}
#'      \item{sport}{Sport of the student}
#'   }
#'
#' @inheritSection data1 Data1 Fields
#'
#' @source xyz
#' @source abc
#'
#' @docType data
"data2"

Note that this removes the actual format of the data from the @format tag, so this may not align with best practices according to the documentation.

How to inherit roxygen documentation from data

1 Answers1