13

I am using the devtools package to check if a package I am developing is ready for submission to CRAN.

Using Roxygen2 through devtools, I documented a small number of functions with #'@export, in order for them to be available when the package I am developing is loaded.

However, when I run devtools::check(), it seems I need to document the functions that are NOT exported, i.e. those that may be called by a function which is exported, but which are not available nor needed by whoever uses the package. Here is an example from the output of devtools::check():

checking Rd \usage sections ... WARNING
Undocumented arguments in documentation object 'calculate_agreement'
  ‘a_assign_star’ ‘a_assign’

Do I need to document those arguments although the function is not exported?

Joshua Rosenberg
  • 4,014
  • 9
  • 34
  • 73
  • 1
    You need to document all arguments to exported functions. This message occurs when you have exported a function but not described all of its arguments. – Thomas Dec 31 '16 at 19:26

1 Answers1

21

I believe the problem here (based on past experience) is that you are probably using Roxygen comment delimiters #' in the preamble to the function. This (I'm pretty sure) triggers the creation of a .Rd file (and the need to document parameters), whether or not you have an @export directive or not. My solution in this case was to use regular # commenting rather than #'.

Based on this answer it's possible that an explicit @keywords internal directive would also work (but I haven't tried it).

Community
  • 1
  • 1
Ben Bolker
  • 211,554
  • 25
  • 370
  • 453
  • So is it considered bad practice to document (with Roxygen I mean) non-exported functions ? It makes them appear in the package documentation while they are not available through normal `::` operator, which could be misleading for the user ? – Romain Feb 26 '19 at 15:39
  • I think if you use the `@keywords internal` directive, all of the non-exported packages will end up on a single "internal" man page (where you could explain why they're there ...? – Ben Bolker Feb 26 '19 at 16:44