Inherits from NSObject
Declared in GBComment.h
GBComment.m

Overview

Handles all comment related stuff.

Each instance describes a single source code comment for any object - class, category, protocol, method... As the comment is universal for each object, it contains properties for all fields applying to any kind of object. However not all are used in all cases. If a property is not used, it's value remains nil . Derived values are:

  • paragraphs : An array of GBCommentParagraph objects. The first entry is considered a short description, also available through firstParagraph .
  • parameters : An array of GBCommentParameter objects. Only applicable for methods with parameters.
  • result : A single GBCommentParameter object. Only applicable for methods with return value.
  • exceptions : An array of GBCommentParameter objects. Only applicable for methods with exceptions.
  • crossrefs : An array of GBParameterLinkItem objects.

All arrays must be provided in the desired order of output - i.e. output formatters don't apply any sorting, they simply emit the values in the given order.

GBComment is not context aware by itself, it's simply a container object that holds comment information. It's the rest of the application that's responsible for setting it's values as needed. In most cases it's GBParser s who sets comments string value and GBProcessor s to parse string value and setup the derived properties based on the comment's context.

Note: Although derived values are prepared based on stringValue , nothing prevents clients to setup derived values directly, "on the fly" if needed. However splitting the interface allows us to simplify parsing code and allow us to handle derives values when we have complete information available.

Tasks

Initialization & disposal

Paragraphs handling

Method arguments handling

Output generator helpers

Input values

Extension Methods

Class Methods

commentWithStringValue:

Returns a new autoreleased instance of the comment with the given string value.

+ (id)commentWithStringValue:(NSString *)value

Parameters

value
String value to set.

Return Value

Returns initialized object or nil if initialization fails.

Discussion

Returns a new autoreleased instance of the comment with the given string value.

This is a helper initializer which allows setting string value with a single message. Sending this message is equivalent to sending commentWithStringValue:sourceInfo: , passing the given value and nil for source info.

See Also

Declared In

GBComment.h

commentWithStringValue:sourceInfo:

Returns a new autoreleased instance of the comment with the given string value and source info.

+ (id)commentWithStringValue:(NSString *)value sourceInfo:(GBSourceInfo *)info

Parameters

value
String value to set.
info
Source info to set.

Return Value

Returns initialized object or nil if initialization fails.

Discussion

Returns a new autoreleased instance of the comment with the given string value and source info.

This is a helper initializer which allows setting default values with a single message.

See Also

Declared In

GBComment.h

Instance Methods

registerCrossReference:

Registers the GBParagraphLinkItem as an explicit, comment-wide, cross reference and adds it to the end of crossrefs array.

- (void)registerCrossReference:(GBParagraphLinkItem *)ref

Parameters

ref
The cross reference to register.

Discussion

Registers the GBParagraphLinkItem as an explicit, comment-wide, cross reference and adds it to the end of crossrefs array.

If crossrefs is nil , a new array is created before adding the given object to it. If a reference to the same object is already registered, a warning is logged and nothing happens.

Exceptions

NSException
Thrown if the given reference is nil .

See Also

Declared In

GBComment.h

registerException:

Registers the GBCommentArgument that describes an exception the method can raise and adds it to the end of exceptions array.

- (void)registerException:(GBCommentArgument *)exception

Parameters

exception
Exception to register.

Discussion

Registers the GBCommentArgument that describes an exception the method can raise and adds it to the end of exceptions array.

If exceptions is nil , a new array is created before adding the given object to it. If an exception with the same name is already registered, a warning is logged and previous item is replaced with the given one.

Exceptions

NSException
Thrown if the given exception is nil .

See Also

Declared In

GBComment.h

registerParagraph:

Registers the GBCommentParagraph and adds it to the end of paragraphs array.

- (void)registerParagraph:(GBCommentParagraph *)paragraph

Parameters

paragraph
Paragraph to register.

Discussion

Registers the GBCommentParagraph and adds it to the end of paragraphs array.

If paragraphs is nil , a new array is created before adding the given object to it and the given paragraph is assigned as firstParagraph (the object is also added to paragraphs array!).

Exceptions

NSException
Thrown if the given paragraph is nil .

See Also

Declared In

GBComment.h

registerParameter:

Registers the GBCommentArgument that describes a parameter and adds it to the end of parameters array.

- (void)registerParameter:(GBCommentArgument *)parameter

Parameters

parameter
Parameter to register.

Discussion

Registers the GBCommentArgument that describes a parameter and adds it to the end of parameters array.

If parameters is nil , a new array is created before adding the given object to it. If a parameter with the same name is already registered, a warning is logged and previous item is replaced with the given one.

Exceptions

NSException
Thrown if the given parameter is nil or [GBCommentArgument argumentName] is nil or empty string.

See Also

Declared In

GBComment.h

registerResult:

Registers the GBCommentParagraph that describes method return value.

- (void)registerResult:(GBCommentParagraph *)result

Parameters

result
Result to register.

Discussion

Registers the GBCommentParagraph that describes method return value.

If a result is already registered, a warning is logged and previous result is replaced with the given one.

Exceptions

NSException
Thrown if the given result is nil .

See Also

Declared In

GBComment.h

replaceParametersWithParametersFromArray:

Replaces all registered parameters with the objects from the given array.

- (void)replaceParametersWithParametersFromArray:(NSArray *)array

Parameters

array
The array of parameters to register.

Discussion

Replaces all registered parameters with the objects from the given array.

The given array should only contain GBCommentArgument objects. If there are any parameters registered, they will be removed first! If nil or empty array is passed, current parameters are removed only.

Exceptions

NSException
Thrown if any of the objects is invalid, see registerParameter: for details.

Declared In

GBComment.h

Properties

crossrefs

NSArray containing all explicit cross references as described within the comment.

@property (readonly) NSArray *crossrefs

Discussion

NSArray containing all explicit cross references as described within the comment.

Cross references can point to an URL, local member, another object or remote member. They are listed in the order as declared in the comment. Each object is a GBParagraphLinkItem instance and should be registered through registerCrossReference: method.

See Also

Declared In

GBComment.h

exceptions

NSArray containing all exceptions commented method can raise as described within the comment.

@property (readonly) NSArray *exceptions

Discussion

NSArray containing all exceptions commented method can raise as described within the comment.

Exceptions are in the order of declaration in the comment. Each object is a GBCommentArgument instance and should be registered through registerException: method.

See Also

Declared In

GBComment.h

firstParagraph

The first paragraph from paragraphs list or nil if no paragraph is registered.

@property (retain) GBCommentParagraph *firstParagraph

Discussion

The first paragraph from paragraphs list or nil if no paragraph is registered.

The value is automatically returned from paragraphs list, it doesn't have to be manually registered. However if needed, it can still be set manually if needed.

Declared In

GBComment.h

hasCrossrefs

Indicates whether the comment has at least one cross reference or not.

@property (readonly) BOOL hasCrossrefs

Discussion

Indicates whether the comment has at least one cross reference or not.

This is used mainly to simplify template output generators. Programmatically this method is equal to testing whether crossrefs count is greater than 0, like this: [object.crossrefs count] > 0 .

See Also

Declared In

GBComment.h

hasExceptions

Indicates whether the comment has at least one exception or not.

@property (readonly) BOOL hasExceptions

Discussion

Indicates whether the comment has at least one exception or not.

This is used mainly to simplify template output generators. Programmatically this method is equal to testing whether exceptions count is greater than 0, like this: [object.exceptions count] > 0 .

See Also

Declared In

GBComment.h

hasMultipleParagraphs

Indicates whether the comment has at least two paragraphs or not.

@property (readonly) BOOL hasMultipleParagraphs

Discussion

Indicates whether the comment has at least two paragraphs or not.

This is used mainly to simplify template output generators. Programmatically this method is equal to testing whether paragraph count is greater than 1, like this: [object.paragraphs count] > 1 .

See Also

Declared In

GBComment.h

hasParagraphs

Indicates whether the comment has at least one paragraph or not.

@property (readonly) BOOL hasParagraphs

Discussion

Indicates whether the comment has at least one paragraph or not.

This is used mainly to simplify template output generators. Programmatically this method is equal to testing whether paragraph count is greater than 0, like this: [object.paragraphs count] > 0 .

See Also

Declared In

GBComment.h

hasParameters

Indicates whether the comment has at least one parameter or not.

@property (readonly) BOOL hasParameters

Discussion

Indicates whether the comment has at least one parameter or not.

This is used mainly to simplify template output generators. Programmatically this method is equal to testing whether parameters count is greater than 0, like this: [object.parameters count] > 0 .

See Also

Declared In

GBComment.h

paragraphs

NSArray containing all paragraphs of the comment.

@property (readonly) NSArray *paragraphs

Discussion

NSArray containing all paragraphs of the comment.

The paragraphs are in same order as in the source code. First paragraph is used for short description and is also available via firstParagraph . Each object is a GBCommentParagraph instance and should be registered through registerParagraph: method.

See Also

Declared In

GBComment.h

parameters

NSArray containing all method parameters described within the comment.

@property (readonly) NSArray *parameters

Discussion

NSArray containing all method parameters described within the comment.

Parameters are in the order of declaration within code regardless of the order declared in the comment! Each object is a GBCommentArgument instance and should be registered through registerParameter: method.

See Also

Declared In

GBComment.h

result

The description of the method result or nil if this is not method comment or method has no result.

@property (readonly, retain) GBCommentParagraph *result

Discussion

The description of the method result or nil if this is not method comment or method has no result.

The description is a GBCommentParagraph instance and should be registerResult: to register the result.

See Also

Declared In

GBComment.h

sourceInfo

Comment's source file info.

@property (retain) GBSourceInfo *sourceInfo

Declared In

GBComment.h

stringValue

Comment's raw string value as declared in source code.

@property (copy) NSString *stringValue

Declared In

GBComment.h