[Rd] Documentation responsibility for functions and methods

[John Chambers]

A revised version of the undoc() function in the tools package was
committed to r-devel today that attempts to implement the following
policy in checking for undocumented functions and methods in a package,
based on discussions recently on this list and in r-core:

If a package has methods for a function defined originally somewhere
else, and does not change the underlying default method for the
function, the package is responsible for documenting the methods it
creates, but not for the function itself or the default method.

In particular, if you define methods for functions in the base package,
"R CMD check" will warn you if you have not documented those methods,
but should not ask you to document the function or its default ("ANY")
method.

However, if the function itself is in the same package OR the default
method has been changed from the original non-generic function, then you
should be warned about missing documentation for these two items as
well.

The current implementation is not very strict in deciding whether the
default method has been changed, but will catch the common situations. 
Let us know if you seem to be asked for too much documentation (or too
little, of course).

Regards,
 John

-- 
John M. Chambers                  jmc at bell-labs.com
Bell Labs, Lucent Technologies    office: (908)582-2681
700 Mountain Avenue, Room 2C-282  fax:    (908)582-3340
Murray Hill, NJ  07974            web: http://www.cs.bell-labs.com/~jmc