[R-pkg-devel] 2 Return values for 2 Functions

[Enrico Schumann]

On Tue, 26 Sep 2023, Leonard Mada via R-package-devel writes:

> Dear Members,
>
>
> How should the return values be documented, when the
> help page covers 2 related functions:
>
>
> 1.) Variant 1: fails the checks
>
> \value{
> \code{cryst1} returns a list of class \sQuote{cryst1} with the
> following components:
> \describe{
> \item{abc}{a numeric vector of length 3 containing the norms of the lattice
>   vectors a, b and c.... there are more items}
> }
> \item{}{}
> \code{is.cryst1} returns TRUE if \code{x} is an object
> of class \sQuote{cryst1}
>   and FALSE otherwise.
> }
>
>
> 2.) Variant 2: fails in Latex
>
> \value{
> \code{cryst1} returns a list of class \sQuote{cryst1} with the
> following components:
> \describe{
> \item{abc}{a numeric vector of length 3 containing the norms of the lattice
>   vectors a, b and c.... there are more items}
> }
> \cr\cr
> \code{is.cryst1} returns TRUE if \code{x} is an object
> of class \sQuote{cryst1}
>   and FALSE otherwise.
> }
>
>
> 3.) 2 separate Value-Sections
>
> Did not generate actually 2 sections: only the 1st one.
>
>
> Sincerely,
>
>
> Leonard


Have you tried something like this?

    \value{
      Function \code{xx} evaluates to a list:
      \item{A}{result A}
      \item{B}{result B}
    
      Function \code{yy} evaluates to a list:
      \item{C}{result C}
      \item{D}{result D}  
    }

"Writing R Extensions" says not to use \describe environments;
see https://cran.r-project.org/doc/manuals/R-exts.html#index-_005cvalue :

,----
| Note that \value is implicitly a \describe environment, so
| that environment should not be used for listing components,
| just individual \item{}{} entries.
`----



-- 
Enrico Schumann
Lucerne, Switzerland
http://enricoschumann.net