[Rd] Please avoid direct use of NAMED and SET_NAMED macros

[Radford Neal]

> To allow for future changes in the way the need for duplication is
> detected in R internal C code, package C code should avoid direct
> use of NAMED,and SET_NAMED, or assumptions on the maximal value
> of NAMED. Use the macros MAYBE_REFERENCED, MAYBE_SHARED, and
> MARK_NOT_MUTABLE instead. These currently correspond to
> 
> MAYBE_REFERENCED(x):   NAMED(x) > 0
> MAYBE_SHARED(x):       NAMED(x) > 1
> MARK_NOT_MUTABLE(x):   SET_NAMED(c, NAMEDMAX)
> 
> Best,
> 
> luke


Checking https://cran.r-project.org/doc/manuals/r-release/R-exts.html
shows that currently there is no mention of these macros in the
documentation for package writers.  Of course, the explanation of
NAMED there also does not adequtely describe what it is supposed to
mean, which may explain why it's often not used correctly.

Before embarking on a major change to the C API, I'd suggest that you
produce clear and complete documention on the new scheme.

    Radford Neal