Introduction

Good, concise documentation is essential if other developers want to use the framework. To create the API documentation we use doxygen.

Required Tools

Doxygen is not part of the apple developers tools. It can be downloaded here. Doxygen.app should be installed in /Applications.

Doxygen relies on an external program, Graphviz, to generate graphical class diagrams. It can be downloaded here.

Building the Documentation

The Mac project file (CorePlot.xcodeproj) contains a build target called "Documentation". This target compiles the documentation and automatically adds a documentation feed to the XCode documentation. The documentation produced applies to both the Mac and iPhone versions of Core Plot.

Documentation Policy

This section describe how and where the code should be documented. Doxygen supports two ways of putting commands in comments, with slashes and with @-signs, we use @-signs. All documentation goes into the implementation(.m) file with the exception of protocol declarations, struct definitions, enum declarations, and grouping commands that doxygen requires to be in the header file.

Classes

The class documentation block goes just before the @implementation of the implementation file. The documentation should consist of a @brief stating the purpose of the class in one sentence and a more elaborate description on the purpose, use and subclassing of the class. Think of this as a 'Overview' section in Apple's API documentation. If the classes has multiple initializers, indicate the designated initializer.

Properties

Properties are documented before their @synthesize or @dynamic using a comment block as follows:

/** @property myProperty
 *  @brief Property is very useful
 *  Useful and there is a lot more to tell about this property **/
@synthesize myProperty;

The @property is required as doxygen cannot find the property name otherwise.

Accessor properties like readonly, copy/retain/assign, and nonatomic are automatically added and should not occur in the manual part of the documentation.

Member functions

Member functions are documented just before the implementation. The documentation block should always include a @brief and a description as well as a description of the parameters and return value using the @param and @return commands.

Structs and enums

Structures and enumerations are defined and documented in the header file. They require at least a @brief description for the struct or enum as a whole and for each component. The single line shorthand documentation comment (///<) can be used for the individual components.

/**
 *	@brief RGBA color for gradients
 **/
typedef struct _CPRGBAColor {
	CGFloat red;	///< The red component (0 ≤ red ≤ 1).
	CGFloat green;	///< The green component (0 ≤ green ≤ 1).
	CGFloat blue;	///< The blue component (0 ≤ blue ≤ 1).
	CGFloat alpha;	///< The alpha component (0 ≤ alpha ≤ 1).
} CPRGBAColor;

Implementation

#import "CPColorSpace.h"

@interface CPColorSpace ()

+(CGColorSpaceRef)createGenericRGBSpace;

-(void)setCGColorSpace:(CGColorSpaceRef)newSpace;

@end

/** @brief Wrapper around CGColorSpaceRef
 *  A wrapper class around CGColorSpaceRef
 *
 * @todo More documentation needed 
 **/

@implementation CPColorSpace

/** @property cgColorSpace. 
 * @brief The CGColorSpace to wrap around **/
@synthesize cgColorSpace;


/** @brief Creates and returns a instance of CPColorSpace initialized with the standard RGB space
 * Creates and returns a instance of CPColorSpace initialized with the standard RGB space. 
 * For the iPhone this is CGColorSpaceCreateDeviceRGB(), for Mac OS X CGColorSpaceCreateWithName(kCGColorSpaceGenericRGB).
 **/
+(CGColorSpaceRef)createGenericRGBSpace;
{
#if TARGET_IPHONE_SIMULATOR ||TARGET_OS_IPHONE
	return CGColorSpaceCreateDeviceRGB();
#else
	return CGColorSpaceCreateWithName(kCGColorSpaceGenericRGB); 
#endif
} 

// This caches a generic RGB colorspace for repeated use
/** @brief Returns a shared instance of CPColorSpace initialized with the standard RGB space
 * Creates and returns a instance of CPColorSpace initialized with the standard RGB space. 
 * For the iPhone this is CGColorSpaceCreateDeviceRGB(), for Mac OS X CGColorSpaceCreateWithName(kCGColorSpaceGenericRGB).
 *
 *  @return A shared CPColorSpace object initialized with the standard RGB colorspace.
 **/
+(CPColorSpace *)genericRGBSpace;
{ 
	static CPColorSpace *space = nil;
&hellips;

/** @brief Initializes a newly allocated colorspace object with the specified colorSpace
 *  Initializes a newly allocated colorspace object with the specified colorSpace. This is the designated initializer.
 *  @return The initialized CPColorSpace object.
 **/
-(id)initWithCGColorSpace:(CGColorSpaceRef)colorSpace {
    if ( self = [super init] ) {
...

@end