[Rd] [External] Re: Is ALTREP "non-API"?

[iuke-tier@ey m@iii@g oii uiow@@edu]

On Wed, 24 Apr 2024, Hadley Wickham wrote:

> A few more thoughts based on a simple question: how do you determine the
> length of a vector?
>
> Rf_length() is used in example code in R-exts, but I don't think it's
> formally documented anywhere (although it's possible I missed it). Is using
> in an example sufficient to consider a function to be part of the public
> API? If so, SET_TYPEOF() is used in a number of examples, and hence used by
> CRAN packages, but is no longer considered part of the public API.
>
> Rf_xlength() doesn't appear to be mentioned anywhere in R-exts. Does this
> imply that long vectors are not part of the exported API? Or is there some
> other way we should be determining the length of such vectors?
>
> Are the macro variants LENGTH and XLENGTH part of the exported API? Are we
> supposed to use them or avoid them?
>
> Relatedly, I presume that LOGICAL() is the way we're supposed to extract
> logical values from a vector, but it isn't documented in R-exts, suggesting
> that it's not part of the public API?

My pragmatic approach to deciding if an entry point is usable in a
package is to

     grep for it in the installed headers

     grep for it in WRE

     if those are good, check the text in both places to make sure it
     doesn't tell me not to use is

The first two can be automated; the text reading can't for now.

One place this runs into trouble is when the prose in WRE doesn't
explicitly mention the entry point, but says something like 'this one
and similar ones are OK'. A couple of years ago I worked on improving
some of those by explicitly adding some of those implicit ones, which
did sometimes make the text more cumbersome. I'm pretty sure I added
LOGICAL() and RAW() at that point (but may be mis-remebering); they
are there now. In some other cases I left the text alone but added
index entries. That makes them findable with a text search. I think I
got most that can be handled that way, but there may be some others
left. Far from ideal, but at least a step forward.

>
> ---
>
> It's also worth pointing out where R-exts does well, with the documentation
> of utility functions (
> https://cran.r-project.org/doc/manuals/R-exts.html#Utility-functions). I
> think this is what most people would consider documentation to imply, i.e.
> a list of input arguments/types, the output type, and basic notes on their
> operation.
> ---
>
> Finally, it's worth noting that there's some lingering ill feelings over
> how the connections API was treated. It was documented in R-exts only to be
> later removed, including expunging mentions of it in the news. That's
> obviously water under the bridge, but I do believe that there is
> the potential for the R core team to build goodwill with the community if
> they are willing to engage a bit more with the users of their APIs.

As you well know R-core is not a monolith. There are several R-core
members who also are not happy about how that played out and where
that stands now. But there was and is no viable option other than to
agree to disagree. There is really no upside to re-litigating this
now.

Best,

luke

>
> Hadley
>
> 	[[alternative HTML version deleted]]
>
> ______________________________________________
> R-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

-- 
Luke Tierney
Ralph E. Wareham Professor of Mathematical Sciences
University of Iowa                  Phone:             319-335-3386
Department of Statistics and        Fax:               319-335-3017
    Actuarial Science
241 Schaeffer Hall                  email:   luke-tierney using uiowa.edu
Iowa City, IA 52242                 WWW:  http://www.stat.uiowa.edu/