guile-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: api differences between 1.4 and 1.6


From: Marius Vollmer
Subject: Re: api differences between 1.4 and 1.6
Date: 11 Mar 2002 17:23:58 +0100
User-agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.1

Neil Jerram <address@hidden> writes:

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

Yes, but I don't think the approach to split the work into one part
where internal features are marked, and another where the remaining
are documented is the best way to go about this.  When going about to
document something, it should be quite easy to decide whether it is
internal or not.  If you can't do that, you can't document it anyway.

Of course, if anyone wants to mark internal things as such, please go
ahead, in 1.7.  While you are at it, please consider documenting the
things nearby that are not internal.

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

Whether something is internal or not is important, yes, but the rest
of its documentation is important as well, and even more so.

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

Exactly.

To make myself clear, I'm not arguing against marking stuff as
internal with the scm_i_ convention, it's just that I fear that the
process of deciding about who gets this mark without documenting the
rest is wasted work.

So please, if you are going thru the libguile features and consider
marking something as internal, also consider writing proper docs for
the things nearby in the reference manual.



reply via email to

[Prev in Thread] Current Thread [Next in Thread]