From 9d0961497163eeb42a431a31c9792ed469dd5c06 Mon Sep 17 00:00:00 2001 From: Hadley Wickham Date: Tue, 14 Nov 2023 12:55:53 -0600 Subject: [PATCH] Review feedback; make it clear I don't recommend describeIn --- vignettes/reuse.Rmd | 44 ++++++++++---------------------------------- 1 file changed, 10 insertions(+), 34 deletions(-) diff --git a/vignettes/reuse.Rmd b/vignettes/reuse.Rmd index 12fab060..a5f5bc7b 100644 --- a/vignettes/reuse.Rmd +++ b/vignettes/reuse.Rmd @@ -38,10 +38,11 @@ Use it when all functions have the same (or very similar) arguments. ### `@rdname` Use `@rdname ` to include multiple functions in the same page. -The functions will be collected and share the same `@title`, `@description`, `@examples`, etc. +Tags (e.g. `@title`, `@description`, `@examples`) will be combined, across blocks but often this yields text that is hard to understand. +So we recommend that you make one block that contains the title, description, common parameters, examples and so on, and then only document individual parameters in the other blocks. -There are two basic ways to use it. -You can create a dummy documentation block and then add the functions to it. +There are two basic ways to do that. +You can create a standalone documentation block and then add the functions to it. This typically works best when you have a family of related functions and you want to link to that family from other functions (i.e. `trig` in the examples below). ```{r} @@ -84,38 +85,13 @@ ln <- function(x) log(x, exp(1)) ### `@describeIn` -Use `@describeIn ` to document multiple functions together. -It generates a new section named "**Related functions and methods**", further divided into subsections by the type of relationship between the source and the destination documentation. -Each subsection contains a bulleted list describing the function with the specified ``. +An alternative to `@rdname` is `@describeIn`. +It has a slightly different syntax because as well as a topic name, you also provide a brief description for the function, like `@describein topic one sentence description`. +The primary difference between `@rdname` and `@describeIn`, is that `@describeIn` creates a new section containing a bulleted list all of each function, along with its description. +It uses a number of heuristics to determine the heading of this section, depending on you're documenting related functions, methods for a generic, or methods for a class. -You can document several functions which perform slight variations of a task or which use different defaults in one documentation file: - -```{r} -#' Power -#' @param x base -#' @param exp exponent -power <- function(x, exp) x ^ exp - -#' @describeIn power Square a number -square <- function(x) power(x, 2) - -#' @describeIn power Cube a number -cube <- function(x) power(x, 3) -``` - -In this case, both destination and source are "normal" functions, and you can use `` to explain their differences. - -`@describeIn` is also well suited to explain the relationships between functions making up an object oriented (OO) scheme using S3 or S4. -In this case, roxygen will automatically detect whether a source function is a method and document the relationship to the relevant class or generic. -Your new methods will be organised in one of two ways: - -1. If your new method extends a generic in the ``, it will be listed in a section titled "**Methods for generic ``**". - The subsection will include all methods for your new generic, labelled by the class they cover. - -2. If your new method extends another generic, for a class constructed in the destination, it will be listed in a subsection titled "**Methods for class ``**". - It will be labelled by the generic which the method extends. - -While you can mix and match (some) different types of functions with `@describeIn`, the output may quickly become disorienting for users if the functions are not tightly related. +In general, I no longer recommend `@describeIn` because I don't think the heuristics it uses are as good as a thoughtful hand-crafted summary. +If you're currently using `@describeIn`, you can general replace it with `@rdname`, as long as you give some thought to the multiple-function `@description`. ### Order of includes