[Rd] Is ALTREP "non-API"?

[Simon Urbanek]

> On Apr 25, 2024, at 12:55 AM, Hadley Wickham <h.wickham using gmail.com> wrote:
> 
> 
> 
> >>> That is not true at all - the presence of header does not constitute
> >> declaration of something as the R API. There are cases where internal
> >> functions are in the headers for historical or other reasons since the
> >> headers are used both for the internal implementation and packages. That's
> >> why this is in R-exts under "The R API: entry points for C code":
> >>> 
> >>> If I understand your point correctly, does this mean that
> >> Rf_allocVector() is not part of the "official" R API? It does not appear to
> >> be documented in the "The R API: entry points for C code" section.
> >>> 
> >> 
> >> It does, obviously:
> >> https://cran.r-project.org/doc/manuals/R-exts.html#Allocating-storage-1
> > 
> > 
> > I'm just trying to understand the precise definition of the official API
> > here. So it's any function mentioned in R-exts, regardless of which section
> > it appears in?
> > 
> > Does this sentence imply that all functions starting with alloc* are part
> > of the official API?
> > 
> 
> Again, I can only quote the R-exts (few lines below the previous "The R API" quote):
> 
> 
> We can classify the entry points as
> API
> Entry points which are documented in this manual and declared in an installed header file. These can be used in distributed packages and will only be changed after deprecation.
> 
> 
> It says "in this manual" - I don't see anywhere restriction on a particular section of the manual, so I really don't see why you would think that allocation is not part on the API.
> 
> Because you mentioned that section explicitly earlier in the thread. This obviously seems clear to you, but it's not at all clear to me and I suspect many of the wider community. It's frustrating because we are trying our best to do what y'all want us to do, but it feels like we keep getting the rug pulled out from under us with very little notice, and then have to spend a large amount of time figuring out workarounds. That is at least feasible for my team since we have multiple talented folks who are paid full-time to work on R, but it's a huge struggle for most people who are generally maintaining packages in their spare time.
> 


I must be missing something here since I have no idea what you are talking about. The whole point if a stable API is that no rugs are pulled, so in fact it's exactly the opposite of what you claim - the notice is at least a year due to the release cycle, typically more. Unlike many other languages and ecosystems, R public API does not change very often - and R-core is thinking hard about making breaking changes if at all. In fact, I hear more complaints that the API does NOT change and we are too conservative, precisely because we want to avoid unnecessary breakage.

I will not further comment here - all I did was to point out the relevant text from R-exts which is the canonical source of information. If you have issues, find some parts unclear and want to improve the documentation, I would like to invite you to contribute constructively, propose changes, submit patches. The R-exts document has been around for decades, so it seem implausible that all of sudden it is being misunderstood the way you portrayed it, but it is certainly a good idea to improve documentation so contributions are welcome.

Cheers,
Simon