Following the example from R packages by Hadley Wickham and Jenny Bryan. I'm looking at suggested approach to generating documentation using roxygen2 for S4 objects. The example, which is available in section 10.7.2, reads:

Document S4 classes by adding a roxygen block before setClass(). Use @slot to document the slots of the class in the same way you use @param to describe the parameters of a function. Here’s a simple example:

#' An S4 class to represent a bank account.
#'
#' @slot balance A length-one numeric vector
Account <- setClass("Account",
  slots = list(balance = "numeric")
)

Results

If followed this generates two documentation files with identical content. Formally speaking, there is the Account object and Account class described in Account-class.

Considerations

It makes sense to have the Account object as it can be easily to used to create new instances of that class. However, I find that having one documentation entry only available as Account-class would be sufficient.

Solution attempts

Adding #' @rdname Account-class or #' @name Account-class to Account-class still results in two documentation entry being generated.

Questions

1. Is there a practical reason why the one may need two identical documentation entries one Classname and another Classname-class with identical content?
2. What's a good approach to document S4 classes using roxygen2 with files named Classname-class.R and also creating objects Classname <- setClass()? In the desired scenario the following would happen:
   • New class is defined Newclass-class.R file
   • The class definition is of format Newclass <- setClass("Newclass", ...
   • the roxygen tags available in that file result in only one documentation entry: Newclass-class being created