I think moving the option documentation toward something modeled
on the attribute documentation is an excellent idea. The way
attributes are done, the attribute definition has to explicitly
state whether more detailed documentation exists. Having that
"no documentation" statement in the source is the right level of
"you should do this" motivation.
There could be a way to say that the reference manual documentation
is just the online help text, I suppose.
Maybe the "hidden" options should be documented in a separate
section of the reference manual? As they are "hidden" and not
meant to be used normally.
--paulr