discuss-gnustep
[Top][All Lists]
Advanced
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: GNUstep Coding Standard Additions

From: Richard Frith-Macdonald
Subject: Re: GNUstep Coding Standard Additions
Date: Thu, 05 May 2005 17:36:39 +0100 
On 2005-05-05 10:33:26 +0100 Sheldon Gill <sheldon@westnet.net.au> wrote:
The autogsdoc program generates the markup from the headers ... so source 
modifications go hand in hand with markup changes.
In my mind there is a substantial difference between the concepts of "source modifications" and additional documentation mark ups.
Particularly, if the person looking at making the changes is reasonably confident in so far as the documentation is concerned but not coding.
Making a mistake in the doc markup isn't going to be a big deal. Breaking compilation because you've got the conditionals wrong is.
True .... but the whole point of autogsdoc is that the documenmtation markup is in the sourcecode ... so you can break compilation by altering the markup in the comments as easily as by altering the #defines ... though neither is enough of a risk (or so hard to fix if it happens) that it should be a serious point of discussion!
Besides which, the question I was raising is value. What is the real value in keeping them? What is the value in getting rid of them? What is the effort in properly maintaining them. 

I see the choice:
a) Better, more complete documentation which is readily accessible
b) Trawl your way through conditionals in the headers and work it out
If we're to make it easier and better I think (a) has far more value to the project than (b).
This is a straw-man argument ... nobody is or has advocated trawling through conditonals to work things out, and nobody is arguing about the standard of documentation ... we are both proposing the same standard of documentation. You are proposing explicit markup in comments, I'm proposing impicit markup in the form of #ifdefs. In noth cases autogsdoc produces identical xml and html output.
It's a big mistake to assume that, just because we have no use for a feature, the feature should be removed. 

Why? If *we* have no use for a feature, why shouldn't it be removed?
Because you and I are not the only users of GNUstep. If you want software that does exactly what you want ... you can fork your own version, but if you beleive in free software you have to make it good for other people too. 


Should all features be retained forever?
Obviously not ... but that in no way implies that features should be removed just because one person dislikes them. 


Two things ...
1. other people wanted the defines, and we have no evidence that they are no longer wanted. 

Nor do we have evidence that they do.
I get occasional emails about it ... which I woudl consider to be some sort of evidence.
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.
Benefit vs cost. I don't think Apple is going to come after us just because we re-arrange the headers. We use while space differently. We use different formal names. We have different implementations and documentation. We even put some methods/functions in different header to Apple. These things are far more important. API compatibility doesn't constitute copyright infringement. Even in the US.
It may well be that they are very unlikely to come after us ... but it's FSF policy to minimise the risk of that sort of thing, so keeping our headers very different from Apple ones has that as a benefit. I see no benefit to reorganizing on 'functional' lines - since I'm sure we can't agree on exactly what that means. Grouping by operating system version, and alphabetically within such groups would seem a much more useful standard (from the point of view of locating things in the header). 



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.
From your perspective perhaps. Certainly not from mine. The level and accessibility of documentation is very different between the two in my view. The Usefulness factor is IMO much greater with the docs.
I think either you have completely misinterpreted what I said, or are just not making sense to me somehow. The usefulness factor in the documentation is identical, since the documentation is identical in either case. 
What I'm proposing is a superset of your proposal.
In both cases, the gsdoc language is extended to provide additional version information, and this information is present in the xml and html identically. The difference is that, in your proposal, someone has to insert this markup into the comments for each method, wheras in mine, they merely need to put the method declaration in the correct place in the header file so that autogsdoc will automatically insert it.
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. 

Hmm... let me see. Does it:

a) Let new-comers easily read and understand
b) Help in the design phase, prior to coding
c) allow people not confident in source modification to contribute
Again ... the documentation is identical in either case, so there is no difference between the two cases from the point of view of the documentation. From the point of view of the headers, using the #define is obviously clear and has the added advantage of allowing people to enforce compatibility with complie-time defines.
Using the defines in the headers has two advantages over adding explicit markup in the comments - 
1. Less work to do generating the markup.


But potentially more effort in maintenance and checking.
I like the use of 'potentially' ... yes, portentially more effort, also potentially less effort ... IMO less. 


2. Compile time compatibility checking is available.
The alternative I propose allows checking an application's imports against a list. The one check could generate a report of compatibility against multiple targets, including those you have no direct access to.
I could compare the imports of my windows application here on my windows machine and discover that it uses calls from MacOS 10.3 which weren't implemented until gnustep-gui 1.0.2 and so on 

If you want to add some utility to do that, I see no problem....
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. 

I believe we'll gain much more than lose.


So let's gain without losing at all.
reply via email to
[Prev in Thread] Current Thread [Next in Thread]