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

[Kevin Ushey]

On Thu, Apr 25, 2024 at 4:24 AM Ivan Krylov via R-devel
<r-devel using r-project.org> wrote:
>
> On Wed, 24 Apr 2024 15:31:39 -0500 (CDT)
> luke-tierney--- via R-devel <r-devel using r-project.org> wrote:
>
> > We would be better off (in my view, not necessarily shared by others
> > in R-core) if we could get to a point where:
> >
> >      all entry points listed in installed header files can be used in
> >      packages, at least with some caveats;
> >
> >      the caveats are expressed in a standard way that is searchable,
> >      e.g. with a standardized comment syntax at the header file or
> >      individual declaration level.
>
> This sounds almost like Doxygen, although the exact syntax used to
> denote the entry points and the necessary comments is far from the most
> important detail at this point.

I'm guessing Doxygen would be overkill here? I think instead these
would just be structured comments that mark a particular function, or
set of functions, as part of the API -- and some automated tool could
then just pull those functions out into a list of API functions. Then,
we would have a single "source of truth" for what is in the API, and
could be seen at a glance by browsing / grepping the installed R
headers. I see this as a structured way of accomplishing what is
already being done to clarify whether functions are part of the API in
the R headers.

A similar approach would have macros like R_API, or with a bit more
specificity, maybe something like R_API(ALTREP), which would have no
actual definition -- they would exist in the source purely to mark
functions as part of (some subset of) the API. Or, similarly, anything
declared within a block like R_API {} would be considered part of the
API (to avoid the need to tag every declaration individually.) This
would at least make it easy to figure out what functions are part of
the R API, without requiring too much extra maintenance effort from
the R maintainers.

The other alternative I could imagine would be an installed header
like R_ext/API.h, which package authors who want to submit packages to
CRAN would be required to use, with direct usage of other headers
eventually being phased out. But that would be a larger maintenance
burden, unless its generation could be automated (e.g. from the
functions tagged above).

As a side note, it's worth stating that the set of API endpoints that
R Core wants to make available to CRAN packages, versus those that are
intended for other usages (e.g. applications embedding R), are
different sets. But I suspect this discussion is most relevant to R
package authors who wish to submit their packages to CRAN.

> > There are some 500 entry points in the R shared library that are in
> > the installed headers but not mentioned in WRE. These would need to
> > be reviewed and adjusted.
>
> Is there a way for outsiders to help? For example, would it help to
> produce the linking graph (package P links to entry points X, Y)? I
> understand that an entry point being unpopular doesn't mean it
> shouldn't be public (and the other way around), but combined with a
> list of entry points that are listed in WRE, such a graph could be
> useful to direct effort or estimate impact from interface changes.

I'm guessing the most welcome kinds of contributions would be
documentation? IMHO, "documenting an API" and "describing how an API
can be used" are somewhat separate endeavors. I believe R-exts does an
excellent job of the latter, but may not be the right vehicle for the
former. To that end, I believe it would be helpful to have some
structured API documentation as a separate R-api document. Each
documented function would have described inputs, outputs, whether
inputs + outputs require protection from the garbage collector, and
other important usage notes. This is something that I think could be
developed and maintained by community members, with members of the R
community submitting documentation for each of the available API
functions. Such an effort could be started independently from R Core,
but some guidance would be appreciated as far as (1) would such a
document eventually be accepted as part of the official R manuals, and
(2) if so, what would be required of such a document.

> --
> Best regards,
> Ivan
>
> ______________________________________________
> R-devel using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel