[Bioc-devel] S4 Methods Documentation Convention Triggers Warnings

[Martin Maechler]

>>>>> Michael Lawrence \(MICHAFLA\) via Bioc-devel 
>>>>>     on Mon, 28 Nov 2022 12:11:00 -0800 writes:

    > It may be worth revisiting why we arrived at this convention in the first
    > place and see whether the Rd system can be enhanced somehow so that we can
    > achieve the same effect with a more natural syntax.

    > Michael


Yes, I agree.

It may be that in the distant past, Henrik's suggestion
(a version of which I am using myself a lot in *.Rd -- mostly
 *not* related to S4)
did not work correctly, but I know it has worked for years now,
as I use it "all the time".
and not just I.

If I grep in R's *base* package alone,

inside ...../R/src/library/base/man/

grep --color -nH --null -e '\\item{\\code{' *.Rd

starts with

agrep.Rd 42:      \item{\code{cost}:}{maximum number/fraction of match cost
agrep.Rd 44:      \item{\code{all}:}{maximal number/fraction of \emph{all}
agrep.Rd 46:      \item{\code{insertions}:}{maximum number/fraction of insertions}

gives *many* matches for the  base/man/options.Rd page
and (in Emacs where I use the very powerful M-x grep ) end saying

  Grep finished with 265 matches found at Wed Nov 30 12:25:01


Martin


    > On Mon, Nov 28, 2022 at 11:25 AM Deepayan Sarkar <deepayan.sarkar using gmail.com>
    > wrote:

    >> 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