Header File Documentation

With the first assignment due later this week, I thought I’d take a moment to post what the expected level of documentation is. Basically I’m looking for your header file to serve as stand-alone documentation for your enums, typedefs, #defines, classes, categories, protocols, properties 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 decent HTML documentation (I’ve come to prefer Doxygen). However, you are not required to use them — you may instead simply detail the same information in plain-text comment blocks.

For this assignment, the minimal header documentation I’m looking for is along the lines of the code shown below (this is marked up using Doxygen, again your code needn’t be). Implementation files need not be as detailed, instead comments should document code that is non-obvious.

#import <Cocoa/Cocoa.h>

 Maximum speed in the state of MD
#define SPEED_LIMIT 65

 An enumeration representing the gears of an automatic transmission.
typedef enum {
	kDrive,		/**< Represents the forward/drive gear of the transmission */
	kReverse,	/**< Represents the reverse gear of the transmission */
	kPark,		/**< Prevents the wheels from rotating */
	kNeutral	/**< Disengages the transmission */
} Gear;

 An enumeration of automobile pedals.
typedef enum {
	kGas,		/**< The gas pedal (accelerator) */
	kBrake		/**< The brake pedal */
} Pedal;

 A simple class that models an automobile with a given make and model, 
 details what gear the vehicle is in, what pedals are depressed as well
 as the overall odometer reading.
@interface Automobile : NSObject {

	// if you have ivars, you should document them here

 The manufacturer of the automobile (e.g. Ford, Chevrolet, etc.)
@property(copy, readonly) NSString *make;

 The model of the automobile (e.g. Focus, Impala, etc.)
@property(copy, readonly) NSString *model;

 The current gear the automobile is in
@property(assign) Gear gear;

 The odometer reading of the vehicle
@property(assign, readonly) int odometer;

 Initializes a new automobile with the specified make/model and defaults
 the gear to park with an odometer reading of zero.
 @param make The make of the automobile
 @param model The model of the automobile
 @returns The newly initialized automobile
-(id)initWithMake:(NSString *)make 
			Model:(NSString *)model;

 Applies the specified pedal.
 @param pedal The pedal to press
-(void)applyPedal:(Pedal) pedal;

 Releases the specified pedal.
 @param pedal The pedal to release
-(void)releasePedal:(Pedal) pedal;


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 )

Google+ photo

You are commenting using your Google+ 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 )


Connecting to %s

%d bloggers like this: