From b6fd2d632400ee2010cda8d2f0990662bf066412 Mon Sep 17 00:00:00 2001
From: Simon Dedman <simondedman@gmail.com>
Date: Wed, 4 Oct 2023 15:16:35 -0700
Subject: [PATCH 1/2] use_package_doc details for
 https://github.com/r-lib/usethis/issues/1170

---
 R/documentation.R      | 10 ++++++++++
 man/use_package_doc.Rd | 11 +++++++++++
 2 files changed, 21 insertions(+)

diff --git a/R/documentation.R b/R/documentation.R
index 633f120ee..d6dc00a95 100644
--- a/R/documentation.R
+++ b/R/documentation.R
@@ -13,6 +13,16 @@
 #'   Packages](https://r-pkgs.org)
 #' @inheritParams use_template
 #' @export
+#' @details
+#' use_package_doc() leads to an R-CMD-CHECK warning if package shares name with a
+#' function ([Github Issue](https://github.com/r-lib/usethis/issues/1170)). This can be
+#' obviated by including the following lines at the top of your mypackagename-package.R script:
+#'
+#' `@keywords internal`
+#'
+#' `@aliases reprex-package`
+#'
+#' `"_PACKAGE"`
 use_package_doc <- function(open = rlang::is_interactive()) {
   check_is_package("use_package_doc()")
   use_template(
diff --git a/man/use_package_doc.Rd b/man/use_package_doc.Rd
index 264ff4676..ff4f47fca 100644
--- a/man/use_package_doc.Rd
+++ b/man/use_package_doc.Rd
@@ -20,6 +20,17 @@ in multiple places. This \code{.R} file is also a good place for roxygen
 directives that apply to the whole package (vs. a specific function), such as
 global namespace tags like \verb{@importFrom}.
 }
+\details{
+use_package_doc() leads to an R-CMD-CHECK warning if package shares name with a
+function (\href{https://github.com/r-lib/usethis/issues/1170}{Github Issue}). This can be
+obviated by including the following lines at the top of your mypackagename-package.R script:
+
+\verb{@keywords internal}
+
+\verb{@aliases reprex-package}
+
+\code{"_PACKAGE"}
+}
 \seealso{
 The \href{https://r-pkgs.org/man.html}{documentation chapter} of \href{https://r-pkgs.org}{R Packages}
 }

From 6944309f765a50349470b8fcb032483fdbfc3e48 Mon Sep 17 00:00:00 2001
From: Jenny Bryan <jenny.f.bryan@gmail.com>
Date: Fri, 3 Nov 2023 12:40:09 -0700
Subject: [PATCH 2/2] Refinements

---
 R/documentation.R      | 34 ++++++++++++++++++----------------
 man/use_package_doc.Rd | 30 ++++++++++++++++--------------
 2 files changed, 34 insertions(+), 30 deletions(-)

diff --git a/R/documentation.R b/R/documentation.R
index d6dc00a95..6900eb705 100644
--- a/R/documentation.R
+++ b/R/documentation.R
@@ -1,28 +1,30 @@
 #' Package-level documentation
 #'
-#' Adds a dummy `.R` file that will prompt roxygen to generate basic
+#' Adds a dummy `.R` file that will cause roxygen2 to generate basic
 #' package-level documentation. If your package is named "foo", this will make
 #' help available to the user via `?foo` or `package?foo`. Once you call
-#' `devtools::document()`, roxygen will flesh out the `.Rd` file using data from
-#' the `DESCRIPTION`. That ensures you don't need to repeat the same information
-#' in multiple places. This `.R` file is also a good place for roxygen
-#' directives that apply to the whole package (vs. a specific function), such as
-#' global namespace tags like `@importFrom`.
+#' `devtools::document()`, roxygen2 will flesh out the `.Rd` file using data
+#' from the `DESCRIPTION`. That ensures you don't need to repeat (and remember
+#' to update!) the same information in multiple places. This `.R` file is also a
+#' good place for roxygen directives that apply to the whole package (vs. a
+#' specific function), such as global namespace tags like `@importFrom`.
 #'
+#' There is one tricky case: when a **package** named "foo" also has a
+#' **function** named `foo()`. In this case, after running `use_package_doc()`,
+#' there will be an `R CMD check` warning. The solution is to set the `@aliases`
+#' for the package-level help topic by modifying the dummy `.R` file (e.g.,
+#' `foo-package.R`) as shown below (but substitute the name of your package /
+#' function for "foo"):
+#'
+#' ```
+#' #' @keywords internal
+#' #' @aliases foo-package
+#' #' "_PACKAGE"
+#' ```
 #' @seealso The [documentation chapter](https://r-pkgs.org/man.html) of [R
 #'   Packages](https://r-pkgs.org)
 #' @inheritParams use_template
 #' @export
-#' @details
-#' use_package_doc() leads to an R-CMD-CHECK warning if package shares name with a
-#' function ([Github Issue](https://github.com/r-lib/usethis/issues/1170)). This can be
-#' obviated by including the following lines at the top of your mypackagename-package.R script:
-#'
-#' `@keywords internal`
-#'
-#' `@aliases reprex-package`
-#'
-#' `"_PACKAGE"`
 use_package_doc <- function(open = rlang::is_interactive()) {
   check_is_package("use_package_doc()")
   use_template(
diff --git a/man/use_package_doc.Rd b/man/use_package_doc.Rd
index ff4f47fca..6eaa0d6a5 100644
--- a/man/use_package_doc.Rd
+++ b/man/use_package_doc.Rd
@@ -11,25 +11,27 @@ use_package_doc(open = rlang::is_interactive())
 applicable, or via \code{\link[utils:file.edit]{utils::file.edit()}} otherwise.}
 }
 \description{
-Adds a dummy \code{.R} file that will prompt roxygen to generate basic
+Adds a dummy \code{.R} file that will cause roxygen2 to generate basic
 package-level documentation. If your package is named "foo", this will make
 help available to the user via \code{?foo} or \code{package?foo}. Once you call
-\code{devtools::document()}, roxygen will flesh out the \code{.Rd} file using data from
-the \code{DESCRIPTION}. That ensures you don't need to repeat the same information
-in multiple places. This \code{.R} file is also a good place for roxygen
-directives that apply to the whole package (vs. a specific function), such as
-global namespace tags like \verb{@importFrom}.
+\code{devtools::document()}, roxygen2 will flesh out the \code{.Rd} file using data
+from the \code{DESCRIPTION}. That ensures you don't need to repeat (and remember
+to update!) the same information in multiple places. This \code{.R} file is also a
+good place for roxygen directives that apply to the whole package (vs. a
+specific function), such as global namespace tags like \verb{@importFrom}.
 }
 \details{
-use_package_doc() leads to an R-CMD-CHECK warning if package shares name with a
-function (\href{https://github.com/r-lib/usethis/issues/1170}{Github Issue}). This can be
-obviated by including the following lines at the top of your mypackagename-package.R script:
+There is one tricky case: when a \strong{package} named "foo" also has a
+\strong{function} named \code{foo()}. In this case, after running \code{use_package_doc()},
+there will be an \verb{R CMD check} warning. The solution is to set the \verb{@aliases}
+for the package-level help topic by modifying the dummy \code{.R} file (e.g.,
+\code{foo-package.R}) as shown below (but substitute the name of your package /
+function for "foo"):
 
-\verb{@keywords internal}
-
-\verb{@aliases reprex-package}
-
-\code{"_PACKAGE"}
+\if{html}{\out{<div class="sourceCode">}}\preformatted{#' @keywords internal
+#' @aliases foo-package
+#' "_PACKAGE"
+}\if{html}{\out{</div>}}
 }
 \seealso{
 The \href{https://r-pkgs.org/man.html}{documentation chapter} of \href{https://r-pkgs.org}{R Packages}