Merge pull request #1676 from olivroy/inheritparam

reduce duplication of docs

.github/CONTRIBUTING.md

@@ -22,5 +22,8 @@ Once there is consensus that a PR based on the issue would be helpful, adhering
 *  Look at the build status badges before and after making changes; these badges are available in the package [README](https://github.com/rstudio/gt).  
 *  The **gt** package follows the tidyverse [style guide](http://style.tidyverse.org) so please adopt those style guidelines in your submitted code as best as possible.
 *  The internal documentation uses [roxygen2](https://cran.r-project.org/web/packages/roxygen2/vignettes/roxygen2.html); if your contribution requires new or revised documentation ensure that the roxygen comments are added/modified (do not modify any `.Rd` files in the `man` folder).
+
+Many functions share parameters. For common parameters like `rows`, `columns`, `data`, we use [`@inheritParams`](https://roxygen2.r-lib.org/reference/tags-reuse.html) to document them. Only document these parameters if there is a special case for the function you are documenting. In this case, go to `R/format-data.R`, copy the parameter documentation to the desired function and add additional details.
+
 *  We use [testthat](https://cran.r-project.org/web/packages/testthat/) for code coverage; those contributions with test cases included are helpful easier to accept.
 * Ensure that you have signed the contributor license agreement. It will appear as a "Check" on your PR and a comment from "CLAassistant" will also appear explaining whether you have yet to sign. After you sign, you can click the "Recheck" link in that comment and the check will flip to reflect that you've signed.

R/export.R

@@ -69,12 +69,7 @@
 #' package needs to be installed before attempting to save any table as a
 #' `.docx` document.
 #'
-#' @param data *The gt table data object*
-#'
-#'   `obj:<gt_tbl>` // **required**
-#'
-#'   This is the **gt** table object that is commonly created through use of the
-#'   [gt()] function.
+#' @inheritParams fmt_number
 #'
 #' @param filename *Output filename*
 #'
@@ -533,12 +528,7 @@ gtsave_filename <- function(path, filename) {
 #' tags. This option is preferable when using the output HTML table in an
 #' emailing context.
 #'
-#' @param data *The gt table data object*
-#'
-#'   `obj:<gt_tbl>` // **required**
-#'
-#'   This is the **gt** table object that is commonly created through use of the
-#'   [gt()] function.
+#' @inheritParams gtsave
 #'
 #' @param inline_css *Use inline CSS*
 #'
@@ -627,12 +617,7 @@ as_raw_html <- function(
 #' `as.character()` on the created object will result in a single-element vector
 #' containing the LaTeX code.
 #'
-#' @param data *The gt table data object*
-#'
-#'   `obj:<gt_tbl>` // **required**
-#'
-#'   This is the **gt** table object that is commonly created through use of the
-#'   [gt()] function.
+#' @inheritParams gtsave
 #'
 #' @details
 #'
@@ -758,12 +743,7 @@ as_latex <- function(data) {
 #' vector. This object can be used with `writeLines()` to generate a valid .rtf
 #' file that can be opened by RTF readers.
 #'
-#' @param data *The gt table data object*
-#'
-#'   `obj:<gt_tbl>` // **required**
-#'
-#'   This is the **gt** table object that is commonly created through use of the
-#'   [gt()] function.
+#' @inheritParams gtsave
 #'
 #' @param incl_open,incl_close *Include opening/closing braces*
 #'
@@ -904,12 +884,7 @@ as_rtf <- function(
 #' Get the Open Office XML table tag content from a `gt_tbl` object as a
 #' single-element character vector.
 #'
-#' @param data *The gt table data object*
-#'
-#'   `obj:<gt_tbl>` // **required**
-#'
-#'   This is the **gt** table object that is commonly created through use of the
-#'   [gt()] function.
+#' @inheritParams gtsave
 #'
 #' @param align *Table alignment*
 #'
@@ -1174,12 +1149,7 @@ as_word_tbl_body <- function(
 #' The `as_gtable()` function performs the transformation of a `gt_tbl` object
 #' to a `gtable` object.
 #'
-#' @param data *The gt table data object*
-#'
-#'    `obj:<gt_tbl>` // **required**
-#'
-#'   This is the **gt** table object that is commonly created through use of the
-#'   [gt()] function.
+#' @inheritParams gtsave
 #'
 #' @param plot *Render through the graphics device?*
 #'
@@ -1574,12 +1544,7 @@ grid_layout_widths <- function(layout, data) {
 #' (either on the left or right of the content). This stage performs said
 #' attachment.
 #'
-#' @param data *The gt table data object*
-#'
-#'   `obj:<gt_tbl>` // **required**
-#'
-#'   This is the **gt** table object that is commonly created through use of the
-#'   [gt()] function.
+#' @inheritParams fmt_number
 #'
 #' @param build_stage *The build stage of the formatted R data frame*
 #'
@@ -1697,12 +1662,7 @@ extract_body <- function(
 #' contain the `group_id` and `rowname` columns, whereby `rowname` contains
 #' descriptive stub labels for the summary rows.
 #'
-#' @param data *The gt table data object*
-#'
-#'   `obj:<gt_tbl>` // **required**
-#'
-#'   This is the **gt** table object that is commonly created through use of the
-#'   [gt()] function.
+#' @inheritParams extract_cells
 #'
 #' @return A list of data frames containing summary data.
 #'
@@ -1819,21 +1779,9 @@ extract_summary <- function(data) {
 #' Get a vector of cell data from a `gt_tbl` object. The output vector will have
 #' cell data formatted in the same way as the table.
 #'
-#' @param data *The gt table data object*
-#'
-#'   `obj:<gt_tbl>` // **required**
-#'
-#'   This is the **gt** table object that is commonly created through use of the
-#'   [gt()] function.
+#' @inheritParams vec_fmt_number
 #'
-#' @param columns *Columns to target*
-#'
-#'   `<column-targeting expression>` // *default:* `everything()`
-#'
-#'   Can either be a series of column names provided in [c()], a vector of
-#'   column indices, or a select helper function. Examples of select helper
-#'   functions include [starts_with()], [ends_with()], [contains()],
-#'   [matches()], [one_of()], [num_range()], and [everything()].
+#' @inheritParams fmt_number
 #'
 #' @param rows *Rows to target*
 #'
@@ -1848,15 +1796,6 @@ extract_summary <- function(data) {
 #'   We can also use expressions to filter down to the rows we need (e.g.,
 #'   `[colname_1] > 100 & [colname_2] < 50`).
 #'
-#' @param output *Output format*
-#'
-#'   `singl-kw:[auto|plain|html|latex|rtf|word]` // *default:* `"auto"`
-#'
-#'   The output format of the resulting character vector. This can either be
-#'   `"auto"` (the default), `"plain"`, `"html"`, `"latex"`, `"rtf"`, or
-#'   `"word"`. In **knitr** rendering (i.e., Quarto or R Markdown), the `"auto"`
-#'   option will choose the correct `output` value
-#'
 #' @return A vector of cell data extracted from a **gt** table.
 #'
 #' @section Examples:

R/format_data.R

@@ -79,9 +79,7 @@
 #'   This corresponds to the exact number of decimal places to use. A value
 #'   such as `2.34` can, for example, be formatted with `0` decimal places and
 #'   it would result in `"2"`. With `4` decimal places, the formatted value
-#'   becomes `"2.3400"`. The trailing zeros can be removed with
-#'   `drop_trailing_zeros = TRUE`. If you always need `decimals = 0`, the
-#'   [fmt_integer()] function should be considered.
+#'   becomes `"2.3400"`.
 #'
 #' @param n_sigfig *Number of significant figures*
 #'