Merge pull request #404 from krlmlr/doctype-package-finetune

Fine-tune package doc

R/object-defaults.R

@@ -32,9 +32,8 @@ object_defaults.package <- function(x) {
     title = as.character(desc$Title),
     description = as.character(desc$Description),
     # "NULL" prevents addition of default aliases, see also #202
-    aliases = c("NULL", package_suffix(desc$Package)),
-    rdname = package_suffix(desc$Package),
-    name = desc$Package
+    aliases = paste("NULL", desc$Package, package_suffix(desc$Package)),
+    name = package_suffix(desc$Package)
   )
 }
 

tests/testthat/test-package-doc.R

@@ -12,8 +12,9 @@ test_that("can create package documentation", {
     #' @details Details.
     '_PACKAGE'")[[1]]
   )
-  expect_equal(get_tag(out, "name")$values, "roxygen_devtest")
-  expect_equal(get_tag(out, "alias")$values, "roxygen_devtest-package")
+  expect_equal(get_tag(out, "name")$values, "roxygen_devtest-package")
+  expect_equal(get_tag(out, "alias")$values, c("roxygen_devtest",
+                                               "roxygen_devtest-package"))
   expect_equal(get_tag(out, "title")$values, "Package Title")
   expect_equal(get_tag(out, "description")$values, "Package description.")
   expect_equal(get_tag(out, "docType")$values, "package")

vignettes/rd.R

@@ -119,8 +119,7 @@ Account <- setRefClass("Account",
 #'
 #' @format A data frame with 53940 rows and 10 variables
 #' @source \url{http://www.diamondse.info/}
-#' @name diamonds
-NULL
+"diamonds"
 
 ## ------------------------------------------------------------------------
 #' Generate R documentation from inline comments.
@@ -131,10 +130,7 @@ NULL
 #' The only function you're likely to need from \pkg{roxygen2} is
 #' \code{\link{roxygenize}}. Otherwise refer to the vignettes to see
 #' how to format the documentation.
-#'
-#' @docType package
-#' @name roxygen2
-NULL
+"_PACKAGE"
 
 ## ------------------------------------------------------------------------
 #' Foo bar generic

vignettes/rd.Rmd

@@ -292,7 +292,7 @@ Methods with doc strings will be included in the "Methods" section of the class
 
 ## Documenting datasets
 
-Datasets are usually stored as `.rdata` files in `data/` and not as regular R objects in the package. This means you need document them slightly differently: instead of documenting the data directly, you document `NULL`, and use `@name` to tell roxygen2 what dataset you're really documenting.
+Datasets are usually stored as `.rdata` files in `data/` and not as regular R objects in the package. This means you need document them slightly differently: instead of documenting the data directly, you quote the dataset's name.
 
 There are two additional tags that are useful for documenting datasets:
 
@@ -318,15 +318,14 @@ To show how everything fits together, the example below is an excerpt from the r
 #'
 #' @format A data frame with 53940 rows and 10 variables
 #' @source \url{http://www.diamondse.info/}
-#' @name diamonds
-NULL
+"diamonds"
 ```
 
 ## Documenting packages
 
 As well as documenting every exported object in the package, you should also document the package itself. Relatively few packages provide package documentation, but it's an extremely useful tool for users, because instead of just listing functions like `help(package = pkgname)` it organises them and shows the user where to get started.
 
-Package documentation should describe the overall purpose of the package and point to the most important functions. It should not contain a verbatim list of functions or copy of `DESCRIPTION`. This file is for human reading, so pick the most important elements of your package.
+Package documentation should describe the overall purpose of the package and point to the most important functions. It should not contain a verbatim list of functions or copy of `DESCRIPTION` (although title and description are inherited from `DESCRIPTION` by default to help you get started). This file is for human reading, so pick the most important elements of your package.
 
 Package documentation should be placed in `pkgname.R`. Here's an example:
 
@@ -339,21 +338,16 @@ Package documentation should be placed in `pkgname.R`. Here's an example:
 #' The only function you're likely to need from \pkg{roxygen2} is
 #' \code{\link{roxygenize}}. Otherwise refer to the vignettes to see
 #' how to format the documentation.
-#'
-#' @docType package
-#' @name roxygen2
-NULL
+"_PACKAGE"
 ```
 
 Some notes:
 
-* Like for datasets, there isn't a object that we can document directly so
-  document `NULL` and use `@name` to say what we're actually documenting
-
-* `@docType package` indicates that the documentation is for the package.
+* Like for datasets, there isn't a object that we can document directly. Use
+  `"_PACKAGE"` to indicate that you are creating the package's documentation.
   This will automatically add the corect aliases so that both `?pkgname`
-  and `package?pkgname` will find the package help. If there's already
-  a function called `pkgname()`, use `@name roxygen2-package`.
+  and `package?pkgname` will find the package help. This also works if there's
+  already a function called `pkgname()`.
 
 * Use `@references` point to published material about the package that
   users might find helpful.

vignettes/rd.html

@@ -502,7 +502,7 @@ <h3>RC</h3>
 
 <h2>Documenting datasets</h2>
 
-<p>Datasets are usually stored as <code>.rdata</code> files in <code>data/</code> and not as regular R objects in the package. This means you need document them slightly differently: instead of documenting the data directly, you document <code>NULL</code>, and use <code>@name</code> to tell roxygen2 what dataset you&#39;re really documenting.</p>
+<p>Datasets are usually stored as <code>.rdata</code> files in <code>data/</code> and not as regular R objects in the package. This means you need document them slightly differently: instead of documenting the data directly, you quote the dataset&#39;s name.</p>
 
 <p>There are two additional tags that are useful for documenting datasets:</p>
 
@@ -528,16 +528,15 @@ <h2>Documenting datasets</h2>
 #&#39;
 #&#39; @format A data frame with 53940 rows and 10 variables
 #&#39; @source \url{http://www.diamondse.info/}
-#&#39; @name diamonds
-NULL
-#&gt; NULL
+&quot;diamonds&quot;
+#&gt; [1] &quot;diamonds&quot;
 </code></pre>
 
 <h2>Documenting packages</h2>
 
 <p>As well as documenting every exported object in the package, you should also document the package itself. Relatively few packages provide package documentation, but it&#39;s an extremely useful tool for users, because instead of just listing functions like <code>help(package = pkgname)</code> it organises them and shows the user where to get started.</p>
 
-<p>Package documentation should describe the overall purpose of the package and point to the most important functions. It should not contain a verbatim list of functions or copy of <code>DESCRIPTION</code>. This file is for human reading, so pick the most important elements of your package.</p>
+<p>Package documentation should describe the overall purpose of the package and point to the most important functions. It should not contain a verbatim list of functions or copy of <code>DESCRIPTION</code> (although title and description are inherited from <code>DESCRIPTION</code> by default to help you get started). This file is for human reading, so pick the most important elements of your package.</p>
 
 <p>Package documentation should be placed in <code>pkgname.R</code>. Here&#39;s an example:</p>
 
@@ -549,22 +548,18 @@ <h2>Documenting packages</h2>
 #&#39; The only function you&#39;re likely to need from \pkg{roxygen2} is
 #&#39; \code{\link{roxygenize}}. Otherwise refer to the vignettes to see
 #&#39; how to format the documentation.
-#&#39;
-#&#39; @docType package
-#&#39; @name roxygen2
-NULL
-#&gt; NULL
+&quot;_PACKAGE&quot;
+#&gt; [1] &quot;_PACKAGE&quot;
 </code></pre>
 
 <p>Some notes:</p>
 
 <ul>
-<li><p>Like for datasets, there isn&#39;t a object that we can document directly so
-document <code>NULL</code> and use <code>@name</code> to say what we&#39;re actually documenting</p></li>
-<li><p><code>@docType package</code> indicates that the documentation is for the package.
+<li><p>Like for datasets, there isn&#39;t a object that we can document directly. Use
+<code>&quot;_PACKAGE&quot;</code> to indicate that you are creating the package&#39;s documentation.
 This will automatically add the corect aliases so that both <code>?pkgname</code>
-and <code>package?pkgname</code> will find the package help. If there&#39;s already
-a function called <code>pkgname()</code>, use <code>@name roxygen2-package</code>.</p></li>
+and <code>package?pkgname</code> will find the package help. This also works if there&#39;s
+already a function called <code>pkgname()</code>.</p></li>
 <li><p>Use <code>@references</code> point to published material about the package that
 users might find helpful.</p></li>
 </ul>

vignettes/rd.md

@@ -292,7 +292,7 @@ Methods with doc strings will be included in the "Methods" section of the class
 
 ## Documenting datasets
 
-Datasets are usually stored as `.rdata` files in `data/` and not as regular R objects in the package. This means you need document them slightly differently: instead of documenting the data directly, you document `NULL`, and use `@name` to tell roxygen2 what dataset you're really documenting.
+Datasets are usually stored as `.rdata` files in `data/` and not as regular R objects in the package. This means you need document them slightly differently: instead of documenting the data directly, you quote the dataset's name.
 
 There are two additional tags that are useful for documenting datasets:
 
@@ -319,16 +319,15 @@ To show how everything fits together, the example below is an excerpt from the r
 #'
 #' @format A data frame with 53940 rows and 10 variables
 #' @source \url{http://www.diamondse.info/}
-#' @name diamonds
-NULL
-#> NULL
+"diamonds"
+#> [1] "diamonds"
 ```
 
 ## Documenting packages
 
 As well as documenting every exported object in the package, you should also document the package itself. Relatively few packages provide package documentation, but it's an extremely useful tool for users, because instead of just listing functions like `help(package = pkgname)` it organises them and shows the user where to get started.
 
-Package documentation should describe the overall purpose of the package and point to the most important functions. It should not contain a verbatim list of functions or copy of `DESCRIPTION`. This file is for human reading, so pick the most important elements of your package.
+Package documentation should describe the overall purpose of the package and point to the most important functions. It should not contain a verbatim list of functions or copy of `DESCRIPTION` (although title and description are inherited from `DESCRIPTION` by default to help you get started). This file is for human reading, so pick the most important elements of your package.
 
 Package documentation should be placed in `pkgname.R`. Here's an example:
 
@@ -342,22 +341,17 @@ Package documentation should be placed in `pkgname.R`. Here's an example:
 #' The only function you're likely to need from \pkg{roxygen2} is
 #' \code{\link{roxygenize}}. Otherwise refer to the vignettes to see
 #' how to format the documentation.
-#'
-#' @docType package
-#' @name roxygen2
-NULL
-#> NULL
+"_PACKAGE"
+#> [1] "_PACKAGE"
 ```
 
 Some notes:
 
-* Like for datasets, there isn't a object that we can document directly so
-  document `NULL` and use `@name` to say what we're actually documenting
-
-* `@docType package` indicates that the documentation is for the package.
+* Like for datasets, there isn't a object that we can document directly. Use
+  `"_PACKAGE"` to indicate that you are creating the package's documentation.
   This will automatically add the corect aliases so that both `?pkgname`
-  and `package?pkgname` will find the package help. If there's already
-  a function called `pkgname()`, use `@name roxygen2-package`.
+  and `package?pkgname` will find the package help. This also works if there's
+  already a function called `pkgname()`.
 
 * Use `@references` point to published material about the package that
   users might find helpful.