Feedback on how to combine NAMESPACE tags

[ramiromagno]

Hi,

out of frustration of not always remembering how to combine the NAMESPACE tags I decided to put together a cheatsheet...

If you could be so kind to provide feedback I would be really happy! :) Particularly the use cases for each combination. Thanks in advance!

[hadley]

I think you've made this a bit more complicated than necessary:

• It's totally fine to have an internal function that isn't documented.
• I don't think there's ever any point in combining @noRd and @keywords internal
• I don't think there's much point in @keywords internal without @export — why are you providing user facing documentation to a function that the user can't use?

I'd say that there are three types of functions:

• Internal functions that aren't @exported. In the rare case that they need formal docs, use @noRd.
• Developer facing functions: @export + @keyword internal
• User facing functions: @export

[gaborcsardi]

I don't think there's much point in @Keywords internal without @export — why are you providing user facing documentation to a function that the user can't use?

I agree this is pretty rare, but you might want to document a topic for devs, that is not a function, then you would use @keywords internal without an @export:

#' For devs only
#' 
#' Lorem ipsum...
#' 
#' @name developer-docs
#' @keywords internal
NULL

[ramiromagno]

Thank you both for your feedback!

I tried to be exhaustive with the combinations of three tags, even though it does not make sense in several cases. The subtle little colored squares are meant to indicate recommendation status... So according to Hadley there should be only three "green" (recommended) use cases.

@hadley:

It's totally fine to have an internal function that isn't documented.

I agree too. I just wanted to say that it might be desirable to have them documented, even if only slightly. And perhaps I over-interpreted the Tidyverse guidelines about internal fns: https://style.tidyverse.org/documentation.html#internal-functions.

I don't think there's ever any point in combining @noRd and @keywords internal

I had the same feeling, but then I was trying to be exhaustive, and I also found this example by @jennybc : https://github.com/tidyverse/reprex/blob/318363cf7a911010ebb1593765cc21ec207d2d10/R/prex.R#L3-L20. So I felt unsure...

@hadley and @gaborcsardi :

I don't think there's much point in @keywords internal without @export — why are you providing user facing documentation to a function that the user can't use?

@gaborcsardi: I purposely tried to limit the scope of this cheatsheet to the documentation of functions only, because it gets more complicated with other objects, such as classes and methods, and so on.

Still, I think one could abuse of pkgdown to document internal functions because of the ability to use markdown, images, equations, and all that, and hence be motivated to document a package's internal API for other devs... But I understand that it is a bit of a stretch. :)

Another motivation could be documenting C code functions that can be used by other packages. But I understand that using roxygen2 to document C functions might be heretic.

[hadley]

Closing this since hopefully you now have the feedback you need 😄

[ramiromagno]

Indeed, thanks!