update readme for #43

ropensci-review-tools · Sep 25, 2024 · 282862b · 282862b
1 parent 70324f1
commit 282862b
Show file tree

Hide file tree

Showing 4 changed files with 45 additions and 29 deletions.
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,6 +1,6 @@
 Package: srr
 Title: 'rOpenSci' Review Roclets
-Version: 0.1.3.011
+Version: 0.1.3.012
 Authors@R: 
     person("Mark", "Padgham", , "[email protected]", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0003-2172-5265"))

diff --git a/README.Rmd b/README.Rmd
@@ -59,7 +59,8 @@ these symbols, and roclets define what is done with different kinds of tags.
 The [`roxygen2`](https://roxygen2.r-lib.org) package includes roclets to
 process a number of tags; the `srr` package implements custom roclets to
 process several additional tags for use with [rOpenSci](https://ropensci.org)'s
-software review systems.
+software review systems, and to process tags in locations other than just the
+`R/` directory.
 
 At present, the package only contains roclets and associated functions to help
 those developing and reviewing packages submitted to rOpenSci's system for
@@ -77,15 +78,16 @@ The easiest way to install this package is via the associated
 shown there, simply enable the universe with
 
 ```{r options, eval = FALSE}
-options(repos = c(
+options (repos = c (
     ropenscireviewtools = "https://ropensci-review-tools.r-universe.dev",
-    CRAN = "https://cloud.r-project.org"))
+    CRAN = "https://cloud.r-project.org"
+))
 ```
 
 And then install the usual way with,
 
 ```{r install, eval = FALSE}
-install.packages("srr")
+install.packages ("srr")
 ```
 
 Alternatively, the package can be installed by running one of the following
@@ -156,7 +158,7 @@ describes how to link your package with `srr` in order to use these roclets.
 3. Enable your package to use the `srr_stats` roclets by modifying the
    package's `DESCRIPTION` file so that the `Roxygen` line looks like this:
     ```{r roxygen, eval = FALSE}
-    Roxygen: list(markdown = TRUE, roclets = c ("namespace", "rd", "srr::srr_stats_roclet"))
+    Roxygen:list (markdown = TRUE, roclets = c ("namespace", "rd", "srr::srr_stats_roclet"))
     ```
     That will load the ["roclet"](https://roxygen2.r-lib.org) used by this
     package to process the documentation of statistical standards within your
@@ -170,8 +172,9 @@ describes how to link your package with `srr` in order to use these roclets.
    `R/srr_stats_standards.R`, the first few lines of which will look like this:
     ```{r srr_stats_roxygen, echo = FALSE, message = FALSE}
     f <- "./R/srr-stats-standards.R"
-    if (!file.exists (f))
+    if (!file.exists (f)) {
         srr_stats_roxygen ()
+    }
     rso <- readLines (f)
     head (rso)
     ```
@@ -215,7 +218,14 @@ describes how to link your package with `srr` in order to use these roclets.
     or the equivalent
     [`roxygen2::roxygenise()`](https://roxygen2.r-lib.org/reference/roxygenize.html),
     the roclet will scan your package's documentation for the state of
-    standards, and will generate a summary of the result on your screen.
+    standards, and will generate a summary of the result on your screen. Note,
+    however, that the `roxygen2` package [only scans files in the R
+    directory](https://github.com/r-lib/roxygen2/blob/9652d15221109917d46768e836eaf55e33c21633/R/package_files.R#L1-L10),
+    and so this screen output will only summarise standards documented there.
+    Standards documented in other locations such as test files or vignettes
+    will be recognised and processed by the `srr` package, even through they
+    will not be recognised by the `document()/roxygenise()` functions, and so
+    will not appear in their output.
 
 To help developers understand how to use these roclets, this package includes a
 function,

diff --git a/README.md b/README.md
@@ -20,10 +20,10 @@ Standards](https://stats-devguide.ropensci.org/standards.html). Before
 proceeding, the answer to an important question: **[What is a
 “roclet”](https://github.com/r-lib/roxygen2/issues/1086)?**
 
--   A roclet is an object used by the
-    [`roxygen2`](https://roxygen2.r-lib.org) package to convert
-    [`roxygen2`](https://roxygen2.r-lib.org)-style documentation lines
-    into some desired form of output.
+- A roclet is an object used by the
+  [`roxygen2`](https://roxygen2.r-lib.org) package to convert
+  [`roxygen2`](https://roxygen2.r-lib.org)-style documentation lines
+  into some desired form of output.
 
 ## Why then?
 
@@ -52,7 +52,8 @@ with different kinds of tags. The
 [`roxygen2`](https://roxygen2.r-lib.org) package includes roclets to
 process a number of tags; the `srr` package implements custom roclets to
 process several additional tags for use with
-[rOpenSci](https://ropensci.org)’s software review systems.
+[rOpenSci](https://ropensci.org)’s software review systems, and to
+process tags in locations other than just the `R/` directory.
 
 At present, the package only contains roclets and associated functions
 to help those developing and reviewing packages submitted to rOpenSci’s
@@ -70,15 +71,16 @@ The easiest way to install this package is via the associated
 As shown there, simply enable the universe with
 
 ``` r
-options(repos = c(
+options (repos = c (
     ropenscireviewtools = "https://ropensci-review-tools.r-universe.dev",
-    CRAN = "https://cloud.r-project.org"))
+    CRAN = "https://cloud.r-project.org"
+))
 ```
 
 And then install the usual way with,
 
 ``` r
-install.packages("srr")
+install.packages ("srr")
 ```
 
 Alternatively, the package can be installed by running one of the
@@ -151,6 +153,7 @@ roclets.
         ## [6] "Spatial"                                                        
         ## [7] "Time Series"                                                    
         ## [8] "Dimensionality Reduction, Clustering, and Unsupervised Learning"
+        ## [9] "Probability Distributions"
 
     That function also returns links to the full descriptions of each
     category in the [main project
@@ -163,7 +166,7 @@ roclets.
     this:
 
     ``` r
-    Roxygen: list(markdown = TRUE, roclets = c ("namespace", "rd", "srr::srr_stats_roclet"))
+    Roxygen:list (markdown = TRUE, roclets = c ("namespace", "rd", "srr::srr_stats_roclet"))
     ```
 
     That will load the [“roclet”](https://roxygen2.r-lib.org) used by
@@ -233,6 +236,15 @@ roclets.
     [`roxygen2::roxygenise()`](https://roxygen2.r-lib.org/reference/roxygenize.html),
     the roclet will scan your package’s documentation for the state of
     standards, and will generate a summary of the result on your screen.
+    Note, however, that the `roxygen2` package [only scans files in the
+    R
+    directory](https://github.com/r-lib/roxygen2/blob/9652d15221109917d46768e836eaf55e33c21633/R/package_files.R#L1-L10),
+    and so this screen output will only summarise standards documented
+    there. Standards documented in other locations such as test files or
+    vignettes will be recognised and processed by the `srr` package,
+    even through they will not be recognised by the
+    `document()/roxygenise()` functions, and so will not appear in their
+    output.
 
 To help developers understand how to use these roclets, this package
 includes a function,
@@ -293,17 +305,19 @@ project, you agree to abide by its terms.
 
 ## Contributors
 
-
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
 <!-- prettier-ignore-start -->
 <!-- markdownlint-disable -->
 
-All contributions to this project are gratefully acknowledged using the [`allcontributors` package](https://github.com/ropenscilabs/allcontributors) following the [all-contributors](https://allcontributors.org) specification. Contributions of any kind are welcome!
+All contributions to this project are gratefully acknowledged using the
+[`allcontributors`
+package](https://github.com/ropenscilabs/allcontributors) following the
+[all-contributors](https://allcontributors.org) specification.
+Contributions of any kind are welcome!
 
 ### Code
 
 <table>
-
 <tr>
 <td align="center">
 <a href="https://github.com/mpadge">
@@ -324,14 +338,11 @@ All contributions to this project are gratefully acknowledged using the [`allcon
 <a href="https://github.com/ropensci-review-tools/srr/commits?author=maelle">maelle</a>
 </td>
 </tr>
-
 </table>
 
-
 ### Issue Authors
 
 <table>
-
 <tr>
 <td align="center">
 <a href="https://github.com/santikka">
@@ -346,14 +357,11 @@ All contributions to this project are gratefully acknowledged using the [`allcon
 <a href="https://github.com/ropensci-review-tools/srr/issues?q=is%3Aissue+author%3Aschneiderpy">schneiderpy</a>
 </td>
 </tr>
-
 </table>
 
-
 ### Issue Contributors
 
 <table>
-
 <tr>
 <td align="center">
 <a href="https://github.com/jeroen">
@@ -362,9 +370,7 @@ All contributions to this project are gratefully acknowledged using the [`allcon
 <a href="https://github.com/ropensci-review-tools/srr/issues?q=is%3Aissue+commenter%3Ajeroen">jeroen</a>
 </td>
 </tr>
-
 </table>
-
 <!-- markdownlint-enable -->
 <!-- prettier-ignore-end -->
 <!-- ALL-CONTRIBUTORS-LIST:END -->
diff --git a/codemeta.json b/codemeta.json
@@ -8,7 +8,7 @@
   "codeRepository": "https://github.com/ropensci-review-tools/srr",
   "issueTracker": "https://github.com/ropensci-review-tools/srr/issues",
   "license": "https://spdx.org/licenses/MIT",
-  "version": "0.1.3.011",
+  "version": "0.1.3.012",
   "programmingLanguage": {
     "@type": "ComputerLanguage",
     "name": "R",