[Bioc-devel] S4 Methods Documentation Convention Triggers Warnings

[Martin Morgan]

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 using r-project.org> on behalf of Martin Maechler <maechler using stat.math.ethz.ch>
Date: Wednesday, November 30, 2022 at 6:28 AM
To: Michael Lawrence (MICHAFLA) <lawrence.michael using gene.com>
Cc: bioc-devel using r-project.org <bioc-devel using r-project.org>, Kurt Hornik <Kurt.Hornik using 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]]