discuss-gnustep
[Top][All Lists]
Advanced

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






reply via email to

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