> On Apr 25, 2024, at 12:55 AM, Hadley Wickham <h.wick...@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
______________________________________________
R-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
