subject:"Re\: \[Rd\] Not documenting a function and not getting a check error\?"

Re: [Rd] Not documenting a function and not getting a check error?

2023-01-08 Thread Kurt Hornik

> Duncan Murdoch writes:

> On 06/01/2023 5:25 a.m., Kevin Coombes wrote:
>> I am fairly certain that the check for documentation is really just a 
>> check for the presence of the function name in an "alias" line. 

> Yes, that's what the test does, and that's fine.  The problem is with
> the usage test in tools::codoc().  If I had incorrect arguments
> specified for a documented function, I'd be warned.  If I skip the
> usage docs completely, I am not warned.

> I think the test belongs around here in the source:

> https://github.com/r-devel/r-svn/blob/b57918fd104962415a752ea7db12dcf4f3f5219f/src/library/tools/R/QC.R#L585

> If you look there, you see a variable named 
> "functions_in_usages_not_in_code" but nothing named 
> "functions_in_code_not_in_usages".

Actually, IIuc the infrastructure is there, but it is not used.
print.codoc() has

## In general, functions in the code which only have an \alias but
## no \usage entry are not necessarily a problem---they might be
## mentioned in other parts of the Rd object documenting them, or be
## 'internal'.  However, if a package has a namespace, then all
## *exported* functions should have \usage entries (apart from
## defunct functions and S4 generics, see the above comments for
## functions_missing_from_usages).  Currently, this information is
## returned in the codoc object but not shown.  Eventually, we might
## add something like
## functions_missing_from_usages <-
## attr(x, "functions_missing_from_usages")
## if(length(functions_missing_from_usages)) {
## writeLines("Exported functions without usage information:")
## .pretty_print(functions_in_code_not_in_usages)
## writeLines("")
## }
## similar to the above.

which goes back to sometimes 2009 ...

Best
-k

> Duncan Murdoch


> My
>> circumstantial evidence, from a package in the early stages of 
>> development, came from changing the name of a function. I updated 
>> everything else (usage, examples, etc.) but forgot to change the alias. 
>> Got a warning that the newly named function was not documented. It took 
>> me a while to figure out why R CMD check was still complaining.
>> 
>> I am also pretty sure that, when looking for help in at least one 
>> existing package (can't remember which one), I clicked on the link and 
>> got sent to a page that said absolutely nothing about the function I was 
>> interested in.
>> 
>> On Fri, Jan 6, 2023, 4:48 AM Duncan Murdoch > > wrote:
>> 
>> On 05/01/2023 10:10 p.m., Deepayan Sarkar wrote:
>> > On Fri, Jan 6, 2023 at 1:49 AM Duncan Murdoch
>> mailto:murdoch.dun...@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
>> 
>> __
>> R-devel@r-project.org  mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>> 
>> 

> __
> R-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Not documenting a function and not getting a check error?

2023-01-06 Thread Duncan Murdoch

On 06/01/2023 5:25 a.m., Kevin Coombes wrote:
I am fairly certain that the check for documentation is really just a 
check for the presence of the function name in an "alias" line. 

Yes, that's what the test does, and that's fine.  The problem is with 
the usage test in tools::codoc().  If I had incorrect arguments 
specified for a documented function, I'd be warned.  If I skip the usage 
docs completely, I am not warned.	

I think the test belongs around here in the source:

https://github.com/r-devel/r-svn/blob/b57918fd104962415a752ea7db12dcf4f3f5219f/src/library/tools/R/QC.R#L585

If you look there, you see a variable named 
"functions_in_usages_not_in_code" but nothing named 
"functions_in_code_not_in_usages".

Duncan Murdoch

My
circumstantial evidence, from a package in the early stages of 
development, came from changing the name of a function. I updated 
everything else (usage, examples, etc.) but forgot to change the alias. 
Got a warning that the newly named function was not documented. It took 
me a while to figure out why R CMD check was still complaining.

I am also pretty sure that, when looking for help in at least one 
existing package (can't remember which one), I clicked on the link and 
got sent to a page that said absolutely nothing about the function I was 
interested in.

On Fri, Jan 6, 2023, 4:48 AM Duncan Murdoch > wrote:

On 05/01/2023 10:10 p.m., Deepayan Sarkar wrote:
 > On Fri, Jan 6, 2023 at 1:49 AM Duncan Murdoch
mailto:murdoch.dun...@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

__
R-devel@r-project.org  mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Not documenting a function and not getting a check error?

2023-01-06 Thread Kevin Coombes

I am fairly certain that the check for documentation is really just a check
for the presence of the function name in an "alias" line. My circumstantial
evidence, from a package in the early stages of development, came from
changing the name of a function. I updated everything else (usage,
examples, etc.) but forgot to change the alias. Got a warning that the
newly named function was not documented. It took me a while to figure out
why R CMD check was still complaining.

I am also pretty sure that, when looking for help in at least one existing
package (can't remember which one), I clicked on the link and got sent to a
page that said absolutely nothing about the function I was interested in.

On Fri, Jan 6, 2023, 4:48 AM Duncan Murdoch 
wrote:

> On 05/01/2023 10:10 p.m., Deepayan Sarkar wrote:
> > On Fri, Jan 6, 2023 at 1:49 AM Duncan Murdoch 
> 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
>
> __
> R-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

[[alternative HTML version deleted]]

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Not documenting a function and not getting a check error?

2023-01-06 Thread Duncan Murdoch


On 05/01/2023 10:10 p.m., Deepayan Sarkar wrote:

On Fri, Jan 6, 2023 at 1:49 AM Duncan Murdoch  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

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Not documenting a function and not getting a check error?

2023-01-05 Thread Deepayan Sarkar

On Fri, Jan 6, 2023 at 1:49 AM Duncan Murdoch  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.

Best,
-Deepayan

>
> Duncan Murdoch
>
> __
> R-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

__
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

Re: [Rd] Not documenting a function and not getting a check error?

Re: [Rd] Not documenting a function and not getting a check error?

Re: [Rd] Not documenting a function and not getting a check error?

Re: [Rd] Not documenting a function and not getting a check error?

Re: [Rd] Not documenting a function and not getting a check error?

5 matches

Site Navigation

Mail list logo

Footer information