I'm writing an R package and I noticed that a number of other packages are using the @export docstring on some of their functions and I'm trying to find a canonical definition (I'm assuming it marks the function as available for exporting). From the docstring package documentation,
@export, @import, @importFrom These are keywords that are highly useful for and only really make sense in the context of package creation. docstring isn’t meant to be used for full packages so you wouldn’t expect me to comment on these keywords. However, docstring is a nice tool to use in the time before package creation so it is understandable that if somebody thought their code will turn into a package someday that they might want to get a jump start on all of the documentation (including the namespace directives). There is nothing stopping a user from using these keywords. They won’t do anything when used with docstring though.
This confuses me because I do see packages using @export; regardless of whether it's being used in a package or not, I'm not able to extract any useful information from this definition.
What is the definition of the @export docstring and when should it be used?
CodePudding user response：
The @export docstring informs Roxygen to to put the function name in the package NAMESPACE file which means it can be accessed by users after they run library(<packagename>). It should be used for functions that you want consumers of your package to be able to use directly. You may have private helper functions that you don't necessarily want to expose.
CodePudding user response：
From the R packages book here are some excerpts that might help understand.
For a function to be usable outside of your package, you must export it. You export functions that you want other people to use. Generally, it’s better to export too little than too much. It’s easy to export things that you didn’t before; it’s hard to stop exporting a function because it might break existing code. Always err on the side of caution, and simplicity. It’s easier to give people more functionality than it is to take away stuff they’re used to.
You can read the exports section of the book here https://r-pkgs.org/namespace.html#exports .