Re: api differences between 1.4 and 1.6

[Marius Vollmer]

Neil Jerram <address@hidden> writes:

> One of the problems we have, that makes it harder to be rigorous
> about API changes, is that there's a lot of noise in the system, by
> which I mean stuff that (I believe) is not intended to belong to the
> public API, but which is visible in libguile

Right.

> - and hence picked up by tools like scan-api - because (on Unix-like
> systems) there's no way of hiding something that is needed by more
> than one source file.
> 
> How about using the SCM_API macro as a way of being more specific
> about what is in the API?  In practice, this would initially mean
> _removing_ SCM_API from a lot of stuff that has it but shouldn't.

I'd say that SCM_API and the 'public API of libguile' are not
necessarily the same.  SCM_API is there for a technical reason, not
for an organizational one, and making it serve both roles lead to
conflicts.

> In any given release, a mechanism like this would encourage us to be
> much clearer than now about what is intended to be publically
> available, and therefore what needs documentation.

We need to distinguish between maintaining the documentation alongside
changes to the code, and bringing the documentation into sync with the
code.

Ideally, given a release of Guile with a perfectly matching
documentation, any change to the code needs to be accompanied by a
matching change to the documentation.  That is, there wouldn't be a
problem to identify the parts of the documentation that are affected.

Right now, we are not there yet, and there is the problem of
identifying what needs documentation and what should be considered
internal.  But when documenting a feature, figuring out whether it is
only for internal use or part of a the public API should only be a
small part of figuring out how to document it in the first place.

I'm not saying that it is obvious whether something is internal or
public, just that isolating its intern/extern status from the rest of
its meaning is likely not helpful.  We could now go thru the libguile
headers and mark some things as "public" and some other things as
"only for internal use", but I'd expect things not to be so simple,
and instead of only marking the features in the source, we should
probably just write the whole docs for them when thinking about their
intern/extern status.

> (Note that using SCM_API in this way would also be consistent with the
> Win32 DLL requirement - i.e. to mark everything that should be
> exported from the DLL - for which SCM_API was added in the first
> place.)

I don't think it will be consistent.  Because...

> To take one example: `scm_tc16_keyword'.  Is this part of the API?  I
> would argue that `SCM_KEYWORDP' should suffice and so that
> `scm_tc16_keyword' doesn't need to be exported.  So we could remove
> the `SCM_API' in front of its declaration in keywords.h.

But SCM_KEYWORDP uses scm_tc16_keyword internally.  When you remove
SCM_API from scm_tc16_keyword, users of SCM_KEYWORDP will break.

This is where the technical role of SCM_API would conflict with its
organizational role.