[Bioc-devel] S4 Methods Documentation Convention Triggers Warnings

[Henrik Bengtsson]

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