[previously posted on Stack Overflow: http://stackoverflow.com/questions/17034309/hiding-undocumented-functions-in-a-package-use-of-function-name ] I've got some functions I need to make available in a package, and I don't want to export them or write much documentation for them. I'd just hide them inside another function but they need to be available to several functions so doing it that way becomes a scoping and maintenance issue. What is the right way to do this? By that I mean do they need special names, do they go somewhere other than the R subdirectory, can I put them in a single file, etc? I've checked out the manuals (e.g. Writing R Extensions 1.6.1), and what I'm after is like the .internals concept in the core, but I don't see any instructions about how to do this generally. For example, if I have functions foo1 and foo2 in a file foofunc.R, and these are intended for internal use only, should they be called foo1 or .foo1? And the file that holds them, should it be .foofunc.R or foofunc-internals? What should the Rd look like, or do I even need one? I know people do this in packages all the time and I feel like I've seen this somewhere, but I can't find any resources just now. Perhaps a suggestion of a package that does things this way which I could study would be sufficient. Thanks, Bryan
Proper way to implement package internal functions
6 messages · Duncan Murdoch, Rolf Turner, R. Michael Weylandt +1 more
On 12/06/2013 10:44 AM, Bryan Hanson wrote:
[previously posted on Stack Overflow: http://stackoverflow.com/questions/17034309/hiding-undocumented-functions-in-a-package-use-of-function-name ] I've got some functions I need to make available in a package, and I don't want to export them or write much documentation for them. I'd just hide them inside another function but they need to be available to several functions so doing it that way becomes a scoping and maintenance issue. What is the right way to do this? By that I mean do they need special names, do they go somewhere other than the R subdirectory, can I put them in a single file, etc? I've checked out the manuals (e.g. Writing R Extensions 1.6.1), and what I'm after is like the .internals concept in the core, but I don't see any instructions about how to do this generally. For example, if I have functions foo1 and foo2 in a file foofunc.R, and these are intended for internal use only, should they be called foo1 or .foo1? And the file that holds them, should it be .foofunc.R or foofunc-internals? What should the Rd look like, or do I even need one? I know people do this in packages all the time and I feel like I've seen this somewhere, but I can't find any resources just now. Perhaps a suggestion of a package that does things this way which I could study would be sufficient.
The best way to do this is simply not to export those functions in your NAMESPACE file. If you want to use a naming convention internally to remind yourself that those are private, you can do so, but R doesn't force one on you, and there are no really popular conventions in use. R won't complain if you don't document those functions at all. There may have been other advice in the version 1.6.1 manual, but that is seriously out of date, more than 10 years old. I recommend that you update to 3.0.1. Duncan Murdoch
Thanks Duncan... Silly me, it's section 1.6.1 not version 1.6.1! So this warning from check is not a problem in the long run: * checking for missing documentation entries ... WARNING Undocumented code objects: ?ang0to2pi? ?dAB? ?doBoxesIntersect? ... All user-level objects in a package should have documentation entries. if I understand correctly. I guess the reason I didn't find any documentation is the wide lattitude which is possible. Thank you. Bryan
On Jun 12, 2013, at 10:57 AM, Duncan Murdoch <murdoch.duncan at gmail.com> wrote:
On 12/06/2013 10:44 AM, Bryan Hanson wrote:
[previously posted on Stack Overflow: http://stackoverflow.com/questions/17034309/hiding-undocumented-functions-in-a-package-use-of-function-name ] I've got some functions I need to make available in a package, and I don't want to export them or write much documentation for them. I'd just hide them inside another function but they need to be available to several functions so doing it that way becomes a scoping and maintenance issue. What is the right way to do this? By that I mean do they need special names, do they go somewhere other than the R subdirectory, can I put them in a single file, etc? I've checked out the manuals (e.g. Writing R Extensions 1.6.1), and what I'm after is like the .internals concept in the core, but I don't see any instructions about how to do this generally. For example, if I have functions foo1 and foo2 in a file foofunc.R, and these are intended for internal use only, should they be called foo1 or .foo1? And the file that holds them, should it be .foofunc.R or foofunc-internals? What should the Rd look like, or do I even need one? I know people do this in packages all the time and I feel like I've seen this somewhere, but I can't find any resources just now. Perhaps a suggestion of a package that does things this way which I could study would be sufficient.
The best way to do this is simply not to export those functions in your NAMESPACE file. If you want to use a naming convention internally to remind yourself that those are private, you can do so, but R doesn't force one on you, and there are no really popular conventions in use. R won't complain if you don't document those functions at all. There may have been other advice in the version 1.6.1 manual, but that is seriously out of date, more than 10 years old. I recommend that you update to 3.0.1. Duncan Murdoch
On 13/06/13 03:34, Bryan Hanson wrote:
<SNIP>
So this warning from check is not a problem in the long run: * checking for missing documentation entries ... WARNING Undocumented code objects: ?ang0to2pi? ?dAB? ?doBoxesIntersect? ... All user-level objects in a package should have documentation entries. if I understand correctly. I guess the reason I didn't find any documentation is the wide lattitude which is possible.
I think you *might* get flak about the warnings if you submit your package
to CRAN. I find such warnings annoying, anyhow.
To avoid them you can create a *.Rd file listing all the undocumented
functions
in your package with an alias for the name of each such function and a
"usage" line for each such function. Only a mild pain in the pohutukawa,
and it only needs to be done once. (Possibly with some updating if new
undocumented functions are added to the package.)
The *.Rd file can be called anything you like (as long as it ends in
".Rd" and
doesn't conflict with other *.Rd filled. However a fairly common convention
is to name the file "melvin-internal.Rd" where "melvin" is the name of your
package.
cheers,
Rolf Turner
On Jun 12, 2013, at 16:34, Bryan Hanson <hanson at depauw.edu> wrote:
Thanks Duncan... Silly me, it's section 1.6.1 not version 1.6.1! So this warning from check is not a problem in the long run: * checking for missing documentation entries ... WARNING Undocumented code objects: ?ang0to2pi? ?dAB? ?doBoxesIntersect? ... All user-level objects in a package should have documentation entries.
What does your NAMESPACE file say? MW
if I understand correctly. I guess the reason I didn't find any documentation is the wide lattitude which is possible. Thank you. Bryan On Jun 12, 2013, at 10:57 AM, Duncan Murdoch <murdoch.duncan at gmail.com> wrote:
On 12/06/2013 10:44 AM, Bryan Hanson wrote:
[previously posted on Stack Overflow: http://stackoverflow.com/questions/17034309/hiding-undocumented-functions-in-a-package-use-of-function-name ] I've got some functions I need to make available in a package, and I don't want to export them or write much documentation for them. I'd just hide them inside another function but they need to be available to several functions so doing it that way becomes a scoping and maintenance issue. What is the right way to do this? By that I mean do they need special names, do they go somewhere other than the R subdirectory, can I put them in a single file, etc? I've checked out the manuals (e.g. Writing R Extensions 1.6.1), and what I'm after is like the .internals concept in the core, but I don't see any instructions about how to do this generally. For example, if I have functions foo1 and foo2 in a file foofunc.R, and these are intended for internal use only, should they be called foo1 or .foo1? And the file that holds them, should it be .foofunc.R or foofunc-internals? What should the Rd look like, or do I even need one? I know people do this in packages all the time and I feel like I've seen this somewhere, but I can't find any resources just now. Perhaps a suggestion of a package that does things this way which I could study would be sufficient.
The best way to do this is simply not to export those functions in your NAMESPACE file. If you want to use a naming convention internally to remind yourself that those are private, you can do so, but R doesn't force one on you, and there are no really popular conventions in use. R won't complain if you don't document those functions at all. There may have been other advice in the version 1.6.1 manual, but that is seriously out of date, more than 10 years old. I recommend that you update to 3.0.1. Duncan Murdoch
______________________________________________ R-help at r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
Hi Rolf... Thanks. I discovered the approach you described by looking at the source for spatstat, which as it turns out does exactly that. I also discovered by testing that if you don't export a pattern, but rather export the specific names, not including the functions one wants to hide, that the warning goes away. Since it is less work to change the export statement compared to even a minimal Rd, that's the way I went. It's interesting that there is not more info about these options available. Thanks, Bryan
On Jun 12, 2013, at 6:46 PM, Rolf Turner <rolf.turner at xtra.co.nz> wrote:
On 13/06/13 03:34, Bryan Hanson wrote: <SNIP>
So this warning from check is not a problem in the long run: * checking for missing documentation entries ... WARNING Undocumented code objects: ?ang0to2pi? ?dAB? ?doBoxesIntersect? ... All user-level objects in a package should have documentation entries. if I understand correctly. I guess the reason I didn't find any documentation is the wide lattitude which is possible.
I think you *might* get flak about the warnings if you submit your package
to CRAN. I find such warnings annoying, anyhow.
To avoid them you can create a *.Rd file listing all the undocumented functions
in your package with an alias for the name of each such function and a
"usage" line for each such function. Only a mild pain in the pohutukawa,
and it only needs to be done once. (Possibly with some updating if new
undocumented functions are added to the package.)
The *.Rd file can be called anything you like (as long as it ends in ".Rd" and
doesn't conflict with other *.Rd filled. However a fairly common convention
is to name the file "melvin-internal.Rd" where "melvin" is the name of your
package.
cheers,
Rolf Turner