Header File Documentation

I’m posting to address a couple of questions as to the expected level of documentation. Basically I’m looking for your header file to serve as stand-alone documentation for your class and methods. If a developer were given your header file, they should have what they need to start using it.

For those wondering about a JavaDoc equivalent, there are primarily 2 options in the Objective-C world…

I’d recommend using either of the above tools as they are more than capable of generating good HTML documentation, though you are not required to use them. For this assignment, the minimal header documentation I’m looking for is along the lines of the code shown below. Implementation files need not be as detailed, instead comments should document code that is non-obvious.

#import <Cocoa/Cocoa.h>

/*
Person class consisting of a name and age.
*/
@interface Person : NSObject {
  (NSString *)name;
  (int)age;
}

/*
Returns a person with the given name and age.
newName - The name to assign to the Person.
newAge - The age to assign to the Person.
*/
-(id)initWithName:(NSString *)newName age:(int)newAge;

/*
Returns the name of the Person.
*/
-(NSString *)name;

/*
Sets the name of the Person to the specified name.
newName - The new name for the Person.
*/
-(void)setName:(NSString *)newName;

/*
Returns the age of the Person.
*/
-(int)age;

/*
Sets the age of the Person to the specified age.
newAge - The new age for the Person.
*/
-(void)setAge:(int)newAge;

@end
Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: