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?
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.
Note that these docstring comments mean nothing to base R. This is an Roxygen specific annotation to help you build your NAMESPACE file. It's totally possible to build it other ways as well.