[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Documenting API versions
|
From: |
Richard Frith-Macdonald |
|
Subject: |
Re: Documenting API versions |
|
Date: |
Tue, 10 May 2005 05:14:44 +0100 |
On 2005-05-10 01:05:46 +0100 Sheldon Gill <sheldon@westnet.net.au> wrote:
I think we are talking about operating system version/release, and are not
considering specific dates (though I guess we could lookup dates of
various
releases).
I was thinking a separate page/pages could list releases and dates. In the
GNUstep case I was thinking it could also provide a link to the tarball
where
available, along with MD5 sums.
Yes ... and any other version specific summary information such as release
notes.
I think in terms of operating systems, we consider there to be two sets of
versioning.
First is the OpenStep -> OPENSTEP -> MacOS-X line ... ie 'official'
NeXT/Apple releases.
Second is the GNUstep line.
We want to consider two GNUstep lines, one for the base library and one
for
the gui library, as we use different versioning for the two.
Yes, thats my view too with the addition that it should extend beyond just
-base and -gui.
I think two sets of concurrent versions is probably enough ... the vast
majority of projects would only need one (as they are concerned with their
own versioning). The base and gui libraries are somewhat unusual in that
they are clones of a separately released system, and therefore need to say
where they fit in the versioning of that system as well as their own
versioning.
We haven't really discussed deprecation ... but extending the scheme to
include a version of the system at which part of the api was deprecated is
pretty simple.
Oh, I thought we had discussed deprecation. It certainly is clearly laid
out
in my proposal.
Well, you list it as a feature, but we haven't discussed what it is supposed
to do.
I think this is in part because your viewpoint seems to be simply to
consider whether something appears in the documentation or not. For
instance, you don't really discuss how you will consistently extract the
data from the comments and use it ... what it's exact format is to be and
what can be done to prevent typing errors etc from going unnoticed. These
are in a sense minor issues, but they do impact on ease of use and
implementation (with macros, the preprocessor does the validation work, with
formal gsdoc markup, the xml parser does it).
I'm trying to take a view as to how useful something is ... and while
documentation is important, it's not the only consideration.
With versioning, people want to be able to tell whether the code they write
conforms to a particular API or not. The existing mechanism lets them do
that, and my proposed mechanism would let them do it better, but yours
doesn't really address the issue.
Similarly, deprecation goes beyond documentation ... there is good reason to
have optional compile time and/or run time warnings issued about the use of
deprecated code. That means it makes sense to consider how it might be
possible to simply link those features. I've done some work on runtime
warnings, and had been considering getting autogsdoc to recognize the
presence of those warnings and document the fact that a method or function
is deprecated... but I'm tending to the view that we should have both
compile time and run time warnings. That suggests the use of a macro which
could generate a compile time warning, a run time warning, and easily be
noticed by autogsdoc to produce documentation too.
Adding your idea of more detailed version specific information to this would
be interesting...
Also ... how far do you go? I have seen Apple document *four* states of
deprecation -
feature not deprecated, feature not deprecated now but may be in next
release, feature deprecated, feature no longer deprecated.
So, we might want to record a complete deprecation history, or we might want
to only record cases where a feature is either currently deprecated or when
it was deprecated and then removed.
I think Sheldon's summary of his approach is pretty good (seems clear to
me), but his summary of mine (as I hope is apparent from my emails) is
only
vaguely similar to what I was suggesting ... In particular, all but the
last of the advantages he lists for his approach also apply to mine
because, as I keep trying to make clear, I'm advocating a superset of the
functionality (adding compile-time checking that a program doesn't use api
it shouldn't) and a modest simplification of the markup task (markup a
whole chunk of the api in one go) ... It could be easily modified to be
applicable to other projects too I guess.
Well, I disagree that all but one of the same advantages apply:
I still hold that my approach is cognitively and practically simpler. Hence
easier to review and audit.
There we just take different views I suppose. However ....
Cognitively - both are clear/simple, so I think that's a matter of taste.
Practically - Using macros involve less typing for the user, provides
preprocessor aided error checking.
Your proposal has yet to clearly specify handling depreciation.
As I outline above, I don't think there is a real difference there. I
haven't proposed specific details for deprecation, but I don't think you
have really addressed the issue either ... If I wanted to just mark
something as deprecated in a particular version, it would be trivial to
propose adding an extra, optional argument to the macro used to specify
versioning for a group of methods, but I think the problem deserves better
than that.
Parsing and calculating has some (perhaps small) impact on builds when
compared to comments which are entirely skipped. {Minor point, yes}
Being equally pedantic, I might say that the macro processing would have
lower impact because it's only done a few times per file, wheras the
preprocessor needs to read past longer comments when version information is
provided individually for each method/function etc :-)
I think in practice both can be considered zero impact.