Re: GNUstep Coding Standard Additions

[Richard Frith-Macdonald]

On 2005-05-03 03:09:02 +0100 Sheldon Gill <sheldon@westnet.net.au> wrote:

> Richard Frith-Macdonald wrote:
> > > Secondly, I'd like the docs to clearly state the source for 
> > > functions/methods as OpenStep, MacOS (differentiate puma, jaguar, panther 
> > > and tiger) or GS (version).
> >
> > The current documentation does that for Openstep/MacOS/GNUstep ... so 
> > extending the mechanism to differentiate between individual MacOS and 
> > GNUstep releases should be fairly simple ... it's just that it would take 
> > a 
> > lot of time to review methods to find which release each belongs to.  I 
> > guess we could extend the existing STRICT_OPENSTEP/STRICT_MACOS_X 
> > classification, but I think it might be better to add gnustep and openstep 
> > versioning as separate defines or as markup in the comments.
>
> I was thinking purely of the documentation, not source modifications. I was 
> envisaging an improvement to the markup so functions/methods could be 
> easily 
> categorised as I indicated.

The autogsdoc program generates the markup from the headers ... so source 
modifications go hand in hand with markup changes.

> > The advantage of using defines and using #ifdef/#ifndef/#if defined()  is 
> > that people can then easily check that their code does not use features 
> > which are not present in a particular version, however it's a bit more 
> > cumbersome to deal with.
>
> I understand the intended purpose of this but I don't think it delivers 
> value. At the moment the classification of STRICT_MACOS_X is too broad to 
> be 
> of any real benefit. Imo STRICT_OPENSTEP no longer provides any value at 
> all. 
> It certainly did in the earlier days of the project but I think its time is 
> well and truly passed.

I have no use for those defines either ... but they were put in because 
others *do* have a use for them and asked for them ... even the old openstep 
compatibility!
It's a big mistake to assume that, just because we have no use for a 
feature, the feature should be removed.
Adding a more fine grained control of the MACOS-X information would 
obviously be an improvement.


> > I would prefer to continue with making sure that the defines in the header 
> > files mark the classification of each method accurately, and extend 
> > autogsdoc to generate such a table using that information... then the 
> > table 
> > can be kept in sync with the text of the documentation easily.
>
> As I said previously, I don't think the defines provide enough value for 
> the 
> effort to maintain it. Dropping them would allow the headers to be 
> re-organised along functional lines and I think that is more valuable to 
> the 
> project than the conditional header route.

Two things ...
1. other people wanted the defines, and we have no evidence that they are no 
longer wanted.
2. headers should *not* be organised on functional lines ... Apple do that, 
and we try hard to make headers as dissimilar to Apples as reasonably 
possible, to avoid any possibly accusations of copyright infringement.  This 
is also why we try to pick different formal names for the method arguments 
in the header files, and use whitespace differently from apple.

> Additionally, consider this:
>
> Assume the documentation system has been improved to provide a reasonably 
> fine grained classification. Hence the gsdoc <standards> tag  generated now 
> reflects this.
>
> When a new API is added, the documentation (right above the implementation 
> ;) 
> is tagged appropriately. Easy.

Using #defines in the header achieves the same effect.
In fact, if we order the headers by API version, we can make it even easier, 
since inserting a new method into the correct location in the header gets it 
tagged in the documentation, without us having to write a single additional 
character.

> This is reflected in the gsdoc output. It'd be quite easy for someone to 
> write a small tool to parse the XML output to pick up on the tags needed to 
> automatically generate the complete table.
>
> It'd also be easy to create tool that takes that table and scans for 
> symbols 
> which shouldn't be used.
>
> That would provide a *much* better basis for portability checks and 
> assistance than #ifdef in the headers.

It wouldn't ... because, since the documentation is generated from the 
headers, any possible advantage you can imagine which is based on parsing 
the xml automatically applies to the ifdef in the header solution too.

Using the defines in the headers has two advantages over adding explicit 
markup in the comments -
1. Less work to do generating the markup.
2. Compile time compatibility checking is available.

So .... I agree with the idea of the more finer grained versioning ... but 
it needs to be done as an extension improvement to the current state of 
things rather than losing functionality by requiring explicit markup in the 
comments.