From murdoch@dunc@n @end|ng |rom gm@||@com  Fri Jan  6 10:47:48 2023
From: murdoch@dunc@n @end|ng |rom gm@||@com (Duncan Murdoch)
Date: Fri, 6 Jan 2023 04:47:48 -0500
Subject: [Rd] Not documenting a function and not getting a check error?
In-Reply-To: <CADfFDC5KKOt1GJh8SEZXkQJkDF4O7AVze3TLhE4k7ymGfabdJg@mail.gmail.com>
References: <ba02397f-c3f1-bb53-18c8-31aa91f498c2@gmail.com>
 <CADfFDC5KKOt1GJh8SEZXkQJkDF4O7AVze3TLhE4k7ymGfabdJg@mail.gmail.com>
Message-ID: <515cfe1a-cee1-1434-2ea3-b7f015324658@gmail.com>

On 05/01/2023 10:10 p.m., Deepayan Sarkar wrote:
> On Fri, Jan 6, 2023 at 1:49 AM Duncan Murdoch <murdoch.duncan at gmail.com> wrote:
>>
>> I'm in the process of a fairly large overhaul of the exports from the
>> rgl package, with an aim of simplifying maintenance of the package.
>> During this work, I came across the reverse dependency geomorph that
>> calls the rgl.primitive function.
>>
>> I had forgotten that rgl.primitive was still exported:  I've been
>> thinking of it as an internal function for a few years now.  I was
>> surprised geomorph was able to call it.
>>
>> Particularly surprising to me was the fact that it is not properly
>> documented.  One of the help topics lists it as an alias, but it
>> contains no usage info, and is not mentioned in the .Rd file other than
>> the alias.  And yet "R CMD check rgl" has never complained about it.
>>
>> Is this intentional?
> 
> Does the Rd file that documents it have \keyword{internal}? These are
> not checked fully (as I realized recently while working on the help
> system), and I guess that's intentional.

No, not marked internal.  Here's a simple example:  a package that 
exports f and g, and has only one help page:

---------------------
NAMESPACE:
---------------------
export(f, g)
---------------------

---------------------
R/source.R:
---------------------
f <- function() "this is f"

g <- function() "this is g"
---------------------

---------------------
man/f.Rd:
---------------------
\name{f}
\alias{f}
\alias{g}
\title{
This is f.
}
\description{
This does nothing
}
\usage{
f()
}
---------------------


No complaints about the lack of documentation of g.

Duncan Murdoch



[Rd] Not documenting a function and not getting a check error?
Duncan Murdoch