Re: api differences between 1.4 and 1.6

[Neil Jerram]

>>>>> "Marius" == Marius Vollmer <address@hidden> writes:

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

Yes, as Dirk has also pointed out.  So now we are thinking instead of
being more rigorous about using scm_i_ and SCM_I_ prefixes (as
discussed on the list some time back).

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

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

Agreed.

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

I agree, but given the short term objective of documenting everything
that is _not_ internal, it is helpful (for me) to be able to say "XXX
is internal, so I won't document it", or, conversely, to be able
easily to identify the set of external APIs that haven't yet been
documented.

In the longer term, it would be nice to document even internal stuff.
But that's longer term.

    Marius> I'm not saying that it is obvious whether something is
    Marius> internal or public, just that isolating its intern/extern
    Marius> status from the rest of its meaning is likely not helpful.

I disagree.  It tells (or should tell) the API user how careful we
will be about changing it and about documenting such changes.

    Marius> We could now go thru the libguile headers and mark some
    Marius> things as "public" and some other things as "only for
    Marius> internal use", but I'd expect things not to be so simple,
    Marius> and instead of only marking the features in the source, we
    Marius> should probably just write the whole docs for them when
    Marius> thinking about their intern/extern status.

See above.  Further, it's a good test to try to document only the
intended external API.  If you can't do this such that it all makes
sense, it tells you that you've got the API wrong.

        Neil