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