[Rd] declare and validate options

[Antoine Fabri]

Dear r-devel,

options() are basically global variables and they come with several issues:
* they're not really truly owned by a package aside from loose naming
conventions
* they're not validated
* their documentation is not standard, and they're often not documented at
all, it's hard to know what options exist
* in practice they're sometimes used for internal purposes, which is at
odds with their global nature and contribute to the mess, I think they can
almost always be replaced by objects under a `globals` environment in the
namespace, it's just a bit more work

I tried to do as much as possible with static analysis using my package opt
but it can only go so far : https://github.com/moodymudskipper/opt

I think we can do a bit better and that it's not necessarily so complex,
here's a draft of possible design :

We could have something like this in a package to register options along
with an optional validator, triggered on `options(..)` (or a new function).

# similar to registerS3method() :
registerOption("mypkg.my_option1")
registerOption("mypkg.my_option2", function(x) stopifnot(is.numeric(x))
# maybe a `default` arg too to avoid the .onLoad() gymnastics and invisible
NULL options

* validation is a breaking change so we'd have an environment variable to
opt in
* validation occurs when an option is set AND the namespace is already
loaded (so we can still set options without loading a namespace) OR it
occurs later when an applicable namespace is loaded
* if we register an option that has already been registered by another
package, we get a message, the validator of the last loaded namespace is
used, in practice due to naming conventions it doesn't really happen, CRAN
could also enforce naming conventions for new packages
* New packages must use registerOption() if they define options, and there
must be a standard documentation page for those, separately or together
(with aliases), accessible with `?mypkg.my_option1` etc...

This could certainly be done in different ways and I'd love to hear about
other ideas or obstacles to improvements in this area.

Thanks,

Antoine

	[[alternative HTML version deleted]]