Duplicated documentation in R6

[cbielow]

when documenting (via roxygenize() or Ctrl-Shift-d in R studio) any R6 class in my package using roxygen2_7.2.3 , e.g. the one from the example here (https://www.tidyverse.org/blog/2019/11/roxygen2-7-0-0/#r6-documentation)

i.e. input file

#' R6 Class representing a person
#'
#' A person has a name and a hair color.
Person <- R6::R6Class("Person",
                      public = list(
                        #' @field name First or full name of the person.
                        name = NULL,
                        
                        #' @field hair Hair color of the person.
                        hair = NULL,
                        
                        #' @description
                        #' Create a new person object.
                        #' @param name Name.
                        #' @param hair Hair color.
                        #' @return A new `Person` object.
                        initialize = function(name = NA, hair = NA) {
                          self$name <- name
                          self$hair <- hair
                          self$greet()
                        },
                        
                        #' @description
                        #' Change hair color.
                        #' @param val New hair color.
                        #' @examples
                        #' P <- Person("Ann", "black")
                        #' P$hair
                        #' P$set_hair("red")
                        #' P$hair
                        set_hair = function(val) {
                          self$hair <- val
                        },
                        
                        #' @description
                        #' Say hi.
                        greet = function() {
                          cat(paste0("Hello, my name is ", self$name, ".\n"))
                        }
                      )
)

results in Person.rd (note the duplicated text in \description)

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/person.R
\name{Person}
\alias{Person}
\title{R6 Class representing a person}
\description{
R6 Class representing a person

R6 Class representing a person
}
\details{
A person has a name and a hair color.
}
\examples{
...

> sessionInfo()
R version 4.1.3 (2022-03-10)
Platform: x86_64-w64-mingw32/x64 (64-bit)
Running under: Windows 10 x64 (build 14393)

Matrix products: default

locale:
[1] LC_COLLATE=English_United States.1252  LC_CTYPE=English_United States.1252   
[3] LC_MONETARY=English_United States.1252 LC_NUMERIC=C                          
[5] LC_TIME=English_United States.1252    

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] roxygen2_7.2.3 rmzqc_0.5.2 

loaded via a namespace (and not attached):
 [1] jsonvalidate_1.3.2 digest_0.6.31      brio_1.1.3         ontologyIndex_2.10 R6P_0.3.0         
 [6] R6_2.5.1           jsonlite_1.8.4     lifecycle_1.0.3    magrittr_2.0.3     evaluate_0.21     
[11] rlang_1.1.0        cli_3.6.1          rstudioapi_0.14    testthat_3.1.7     vctrs_0.6.1       
[16] rmarkdown_2.21     tools_4.1.3        purrr_1.0.1        yaml_2.3.7         xfun_0.39         
[21] fastmap_1.1.1      compiler_4.1.3     htmltools_0.5.5    knitr_1.43   

[cbielow]

note: this can be fixed by using

#' @title ...
#'
#' @description
#' ...
#'
#' @details

but that should only be a temporary solution.

[hadley]

Would you mind being a bit more explicit about what the problem is?

[olivroy]

@hadley I recommend looking at the diff in the R and Rd in the PR I opened rstudio/chromote#123

Basically, we need to specify each tag explicitly as implicit @description and @details do not show up explicitly.

The typical roxygen2 pattern used for regular functions doesn't work for R6 classes.

Basically, the diff in Rd files in the PR should not require adding the tags in the R file.

[cbielow]

just to make sure the problem is clear:
This is what roxygen produces (i.e. it duplicates the text, see above for full example)

\description{
R6 Class representing a person

R6 Class representing a person
}

[hadley]

@cbielow yes, that's the output. But what's the input that causes it?

[olivroy]

Here is a reprex for the duplication issue.
I removed the irrelevant part of the output.

library(roxygen2)
# First example: duplicate inherited description
# faulty behavior
roc_proc_text(rd_roclet(), "
  #' Title
  #' @export
  foo <- R6::R6Class()
  ")
#> $foo.Rd
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in ./<text>
#> \name{foo}
#> \alias{foo}
#> \title{Title}
#> \description{
#> Title
#> 
#> Title
#> }
# Expected behavior
roc_proc_text(rd_roclet(), "
  #' Title
  #' 
  #' @description
  #' Title
  #' @export
  foo <- R6::R6Class()
  ")
#> $foo.Rd
#> % Generated by roxygen2: do not edit by hand
#> % Please edit documentation in ./<text>
#> \name{foo}
#> \alias{foo}
#> \title{Title}
#> \description{
#> Title
#> }

^{Created on 2023-11-02 with reprex v2.0.2}

Irrelevant output

```r #> \section{Methods}{ #> \subsection{Public methods}{ #> \itemize{ #> \item \href{#method-unknown-clone}{\code{foo$clone()}} #> } #> } #> \if{html}{\out{

---

}} #> \if{html}{\out{}} #> \if{latex}{\out{\hypertarget{method-unknown-clone}{}}} #> \subsection{Method \code{clone()}}{ #> The objects of this class are cloneable with this method. #> \subsection{Usage}{ #> \if{html}{\out{

}}\preformatted{foo$clone(deep = FALSE)}\if{html}{\out{

}} #> } #> #> \subsection{Arguments}{ #> \if{html}{\out{

}} #> \describe{ #> \item{\code{deep}}{Whether to make a deep clone.} #> } #> \if{html}{\out{

}} #> } #> } #> } ```

Can't replicate for the other issue I get an error

can't replicate the other one with a reprex. ```r roc_proc_text(rd_roclet(), " #' Title #' #' My description #' #' Details #' @export foo <- R6::R6Class('foo', public = list( #' @description A description fn = function() 1L )) ") ``` Error in `map_int()`: ℹ In index: 1. ℹ With name: is_local. Caused by error: ! R6 class lacks source references. ℹ If you are using the `installed` load method in `DESCRIPTION`, then try re-installing the package with option '--with-keep.source', e.g. `install.packages(..., INSTALL_OPTS = "--with-keep.source")`.

[cbielow]

@cbielow yes, that's the output. But what's the input that causes it?

I've edited the original description, but the repex from olivroy is probably faster to reproduce

[hadley]

Thank you!