[Rd] Is ALTREP "non-API"?

[Hiroaki Yutani]

> And in general, I'd urge R Core to make an explicit list of functions that
you consider to be part of the exported API

While I believe R Core is in the process of such clarification, I'd also
vote for this. Now that WRE has "experimental" category, and if we take the
current definition of "documented in the manual" literally, an
"experimental" entry point cannot be documented because the entry point
would promote to an "API" for the obvious reason. It would sound funny that
you cannot write precautionary statements on experimental entry points just
because of the very definition of "experimental". So, I agree R should have
the explicit list.

I'd add that R should also define a process on how to stabilize an
"experimental" or "public" entry point into an "API". For example, Rust
language has such a process [1]. After a feature is introduced as unstable,
a "tracking issue" is filed and the related problems are reported or linked
to it. Users can know what are the remaining problems before getting
stabilized, and, if they have strong will, they can contribute to resolving
such blockers. Similarly, if we can track the unresolved problems of each
non-API, we might be able to help the R core team more smoothly.

Best,
Yutani

[1]: https://rustc-dev-guide.rust-lang.org/stabilization_guide.html


2024年4月24日(水) 21:55 Hadley Wickham <h.wickham using gmail.com>:

> >
> >
> >
> > >>> 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.
>
> For the purposes of this discussion could you please "documented in the
> manual" means? For example, this line mentions allocXxx functions: "There
> are quite a few allocXxx functions defined in Rinternals.h—you may want to
> explore them.". Does that imply that they are documented and free to use?
>
> And in general, I'd urge R Core to make an explicit list of functions that
> you consider to be part of the exported API, and then grandfather in
> packages that used those functions prior to learning that we weren't
> supposed to.
>
> Hadley
>
>
> --
> http://hadley.nz
>
>         [[alternative HTML version deleted]]
>
> ______________________________________________
> R-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

	[[alternative HTML version deleted]]