[Bioc-devel] S4 Methods Documentation Convention Triggers Warnings

[Michael Lawrence (MICHAFLA)]

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

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
>
>
>
> >
> > --------------------------------------
> > 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]]
>
> _______________________________________________
> Bioc-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>


-- 
Michael Lawrence
Senior Principal Scientist, Director of Data Science and Statistical
Computing
Genentech, A Member of the Roche Group
Office +1 (650) 225-7760
michafla using gene.com

Join Genentech on LinkedIn | Twitter | Facebook | Instagram | YouTube

	[[alternative HTML version deleted]]