Re: GNUstep Coding Standard Additions

[Sheldon Gill]

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

> > That said, doing so for everything is a big undertaking. To achieve 
> > this someone will have to research the calls. I'd be happy to baseline 
> > now so that calls are OpenStep, MacOS (panther) or GS current.
>
> We already have that ... are you saying you would review/check that all 
> methods are in the correct grouping?   I think that would be great 
> (there are almost certain to be some misclssifications) ... but if you 
> are happy to review each method in the API, you could make the 
> classification more finely grained (to release versions) if you like.

I'm not saying that *I* would review/check all methods are correctly 
classified but was suggesting that it should be done and would provide 
significant value to the project.

> > Perhaps a new-comer would like to put up their hand to generate a 
> > reference table marking all calls as one of the three?  Strikes me as 
> > a good way to review the API and get familiar with the documentation. 
> > Could be a good assignment for students, too. Anyone teach class?

See? I'm calling for someone to volunteer for this task. It is well 
defined. Quite straight-forward and of value to the project.

It can be easily split into sub-tasks if people are willing to help in part.

It is also of value to someone who wishes to familiarise themselves with 
the API. Basically, they get to read the docs to help themselves and 
contribute back to the project as the same time!

It could concievably be done through wiki or a similar mechanism to make 
collaboration very straight-forward.

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

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.

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.

Someone could get carried away and make such a tool let you know about 
deprecated calls, recommending replacements and alternatives.

This would be re-usable for API versioning checks and portability for 
any associated project, too.

I'd expect that creating the base table would be done just once. The 
autodocs would be revised and the gsdoc output table compared to the 
base table and revisions made until there are no differences. From there 
its about maintaining the documentation markup.

> > Thirdly, I advocate moving GNUstep additions to Additions as far as 
> > possible.
>
> That's already underway... after all,  it's what 'Additions' was 
> introduced for.

Yes. It is relevant to the NS/GS point and if people are going to look 
into that it'd be good to be thinking about moving to Additions at the 
same time.


Regards,
Sheldon