Creating the header
Revision as of 13:10, 7 February 2012
The core GNUstep libraries implement the OpenStep APIs and the newer Cocoa APIs introduced by Apple. The fact that these APIs have been produced by a litigious company, and the GNUstep project is used all over the world, means that we have to be a careful as possible to avoid the possibility of legal action being taken against GNUstep for copyright infringement in any country.
So ... we clearly can't simply copy Apple header files, but must produce our own header files which are functionally equivalent but as different as reasonably possible from the the Apple ones.
The easiest way to see how to do things is simply to look at a gnustep-base or gnustep-gui header file, but this article aims to point out key facts:
We use a standard header at the top of the file, which identifies the file, the copyright ownership (Free Software foundation), the author(s) etc.
We bracket the entire header in preprocessor conditionals to prevent it being used twice if included using the #include mechanism rather than #import.
We #import <GNUstepBase/GSVersionMacros.h> to get version management macros, and we use them to ensure that the header contents are only seen by applications which want to use the version of the API that Apple introduced the class in.
We include a fragment of code at start and end to ensure that the header can be read properly by a C++ compiler.
We list method names within the file as two groups (class methods, and then instance methods) with alphabetical order within each group ... this differs from Apples' usual practice of putting methods together in functional groups.
We use different formal argument names to those that apple use, since changing these does does not effect function of the API.
We use the GNUstep coding standards for line length, the use of white space and indentation. This means individual method names formatted differently than in Apple headers.
We put documentation in comments before each class and before each method (historically the documentation was often put in the source files, but in the header is better).
Have a look at gnustep-base/Headers/Foundation/NSXMLParser.h as an example.