[Bioc-devel] S4 Methods Documentation Convention Triggers Warnings

[Deepayan Sarkar]

On Sun, Nov 27, 2022 at 12:30 PM Dario Strbenac via Bioc-devel <
bioc-devel using r-project.org> wrote:

> Good day,
>
> For a long time, it has been a convention to document S4 methods in the
> format:
>
> \section{Displaying}{
>   In the code snippets below, \code{x} is a GRanges object.
>   \describe{
>     \item{}{
>       \code{show(x)}:
>       Displays the first five and last five elements.
>     }
>   }
> }
>
> In R Under Development, this is now a warning:
>
> * checking Rd files ... WARNING
> checkRd: (5) GRanges-class.Rd:115-165: \item in \describe must have
> non-empty label.
>

> This affects my own package as well as the core Bioconductor packages
> which I used as inspiration for designing my pacakge documentation seven
> years ago. What should the new convention be? Or could R developers be
> convinced to get rid of this check before this prototype is released?
>

The warning is primarily meant for \items inside \arguments, as in HTML
output these now have an id that can be used to link to specific arguments.
The code is shared with \describe, which is why the warning is showing up
here.

So I guess it might be possible to fine-tune the warning to accept this
kind of usage inside \describe. But I think this is a horrible
"convention", and unless this is really widespread that wouldn't be my
first choice.

An alternative to Henrik's suggestion is to just use \itemize instead of
\describe and drop  the first {} after \item.

Best,
-Deepayan



>
> --------------------------------------
> Dario Strbenac
> University of Sydney
> Camperdown NSW 2050
> Australia
> _______________________________________________
> Bioc-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>

	[[alternative HTML version deleted]]