Re: api differences between 1.4 and 1.6

[Neil Jerram]

>>>>> "thi" == Thien-Thi Nguyen <address@hidden> writes:

    thi> [about how to keep better track of API changes between
    thi> versions]

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 - 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.

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.  (From the
documentation point of view, I'd be able to say exactly how near
complete the reference documentation is.)  Between releases, it will
show more clearly what has changed, and (more or less) force us to
document those changes.

It's also a very clear sign to a coder looking through the header
files.  If something is there but doesn't have a SCM_API, the message
is `no guarantees of documentation, stability, etc.; use at your own
risk'.

(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.)

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.

Another example: all the `coop_*' stuff?

If we agree that this is a good idea, we could start introducing it in
1.5/1.6, even though 1.5/1.6 don't currently have SCM_API.  (SCM_API
can be useful as a marker even if it macros to nothing.)

Thoughts?

        Neil