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?
--------------------------------------
Dario Strbenac
University of Sydney
Camperdown NSW 2050
Australia
[Bioc-devel] S4 Methods Documentation Convention Triggers Warnings
7 messages · Dario Strbenac, Henrik Bengtsson, Deepayan Sarkar +3 more
What about:
\item{\code{show(x)}}{
Displays the first five and last five elements.
}
?
On Sat, Nov 26, 2022, 23:00 Dario Strbenac via Bioc-devel <
bioc-devel at 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?
--------------------------------------
Dario Strbenac
University of Sydney
Camperdown NSW 2050
Australia
_______________________________________________ Bioc-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/bioc-devel
On Sun, Nov 27, 2022 at 12:30 PM Dario Strbenac via Bioc-devel <
bioc-devel at 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 at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/bioc-devel
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 at gmail.com> wrote:
On Sun, Nov 27, 2022 at 12:30 PM Dario Strbenac via Bioc-devel < bioc-devel at 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 at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/bioc-devel
[[alternative HTML version deleted]]
_______________________________________________ Bioc-devel at 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 at gene.com Join Genentech on LinkedIn | Twitter | Facebook | Instagram | YouTube [[alternative HTML version deleted]]
1 day later
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
I recently made the change Henrik suggests in the ?devel? but not ?release? branch of BiocParallel, so the manuals can be compared. Take a look at the ?Constructor? and ?Accessors: Logging and results? sections of the ?SnowParam-class.Rd? man page, starting on p. 53 of the PDF. https://bioconductor.org/packages/release/bioc/manuals/BiocParallel/man/BiocParallel.pdf https://bioconductor.org/packages/devel/bioc/manuals/BiocParallel/man/BiocParallel.pdf I think in \item{<foo>}{bar} the <foo> is not wrapped, so runs off the margin in the devel ?Constructor? section. The shorter items in the ?Accessors: Logging and results? section look almost identical, with a little extra (unnecessary) indentation under the original formatting. I changed the ?Accessors: Back-end control? to an itemized list, since there was no description associated with each item. This adds bullets. The commit is at https://code.bioconductor.org/browse/BiocParallel/commit/4e85b38b92f2adb68fe04ffb0476cbc47c1241a8 (as well as https://github.com/Bioconductor/BiocParallel...) Martin From: Bioc-devel <bioc-devel-bounces at r-project.org> on behalf of Martin Maechler <maechler at stat.math.ethz.ch> Date: Wednesday, November 30, 2022 at 6:28 AM To: Michael Lawrence (MICHAFLA) <lawrence.michael at gene.com> Cc: bioc-devel at r-project.org <bioc-devel at r-project.org>, Kurt Hornik <Kurt.Hornik at wu.ac.at> Subject: Re: [Bioc-devel] S4 Methods Documentation Convention Triggers Warnings
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{<file:///item%7b/code%7b>' *.Rd
starts with
agrep.Rd
I think in \item{<foo>}{bar} the <foo> is not wrapped, so runs off the margin in the devel ?Constructor? section.
Would a hack be to split up the \code{} in multiple ones, e.g.
\item{
\code{SnowParam(workers = snowWorkers(), type=c("SOCK", "MPI"),}
\code{tasks = 0L, stop.on.error = FALSE,}
\code{progressbar = FALSE, RNGseed = NULL,}
\code{timeout = Inf, exportglobals = TRUE,}
\code{exportvariables = TRUE,}
\code{log = FALSE, threshold = "INFO", logdir = NA_character_,}
\code{resultdir = NA_character_, jobname = "BPJOB",}
\code{manager.hostname = NA_character_,}
\code{manager.port = NA_integer_,}
\code{...)}}:}{
Does that line wrap?
/Henrik
On Wed, Nov 30, 2022 at 8:21 AM Martin Morgan <mtmorgan.bioc at gmail.com> wrote:
I recently made the change Henrik suggests in the ?devel? but not ?release? branch of BiocParallel, so the manuals can be compared. Take a look at the ?Constructor? and ?Accessors: Logging and results? sections of the ?SnowParam-class.Rd? man page, starting on p. 53 of the PDF. https://bioconductor.org/packages/release/bioc/manuals/BiocParallel/man/BiocParallel.pdf https://bioconductor.org/packages/devel/bioc/manuals/BiocParallel/man/BiocParallel.pdf I think in \item{<foo>}{bar} the <foo> is not wrapped, so runs off the margin in the devel ?Constructor? section. The shorter items in the ?Accessors: Logging and results? section look almost identical, with a little extra (unnecessary) indentation under the original formatting. I changed the ?Accessors: Back-end control? to an itemized list, since there was no description associated with each item. This adds bullets. The commit is at https://code.bioconductor.org/browse/BiocParallel/commit/4e85b38b92f2adb68fe04ffb0476cbc47c1241a8 (as well as https://github.com/Bioconductor/BiocParallel...) Martin From: Bioc-devel <bioc-devel-bounces at r-project.org> on behalf of Martin Maechler <maechler at stat.math.ethz.ch> Date: Wednesday, November 30, 2022 at 6:28 AM To: Michael Lawrence (MICHAFLA) <lawrence.michael at gene.com> Cc: bioc-devel at r-project.org <bioc-devel at r-project.org>, Kurt Hornik <Kurt.Hornik at wu.ac.at> Subject: Re: [Bioc-devel] S4 Methods Documentation Convention Triggers Warnings
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{<file:///item%7b/code%7b>' *.Rd
starts with
agrep.Rd
[[alternative HTML version deleted]]
_______________________________________________ Bioc-devel at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/bioc-devel