[Bioc-devel] S4 Methods Documentation Convention Triggers Warnings

[Deepayan Sarkar]

On Wed, Nov 30, 2022 at 9:51 PM 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.


This should ideally use \preformatted{}, but R-exts says that "Due to
limitations in LaTeX as of this writing, this macro may not be nested
within other markup macros other than \dQuote and \sQuote, as errors or bad
formatting may result."

Still, in this particular case, and possibly others like it, free-format
text (instead of itemizing) might work better:

\section{Constructor}{

    \preformatted{SnowParam(workers = snowWorkers(), type=c("SOCK", "MPI"),
          tasks = 0L, stop.on.error = FALSE,
          progressbar = FALSE, RNGseed = NULL,
          timeout = Inf, exportglobals = TRUE,
          exportvariables = TRUE,
          log = FALSE, threshold = "INFO", logdir = NA_character_,
          resultdir = NA_character_, jobname = "BPJOB",
          manager.hostname = NA_character_,
          manager.port = NA_integer_,
          ...)}
    Returns an object representing a SNOW cluster. The cluster is not
    created until \code{bpstart} is called. Named arguments in \code{...}
    are passed to \code{makeCluster}.

}

Even if we retain the status quo, the \item{}{\code{...}{}} version of this
(as in the release branch) is by no means nice-looking.

Best,
-Deepayan

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
>

	[[alternative HTML version deleted]]