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.sar...@gmail.com>
wrote:
> On Sun, Nov 27, 2022 at 12:30 PM Dario Strbenac via Bioc-devel <
> bioc-devel@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@r-project.org mailing list
> > https://stat.ethz.ch/mailman/listinfo/bioc-devel
> >
>
> [[alternative HTML version deleted]]
>
> _______________________________________________
> Bioc-devel@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
micha...@gene.com
Join Genentech on LinkedIn | Twitter | Facebook | Instagram | YouTube
[[alternative HTML version deleted]]
_______________________________________________
Bioc-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/bioc-devel
