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 GBCommentArgument objects. Only applicable for methods with parameters.
  • result: A single GBCommentArgument object. Only applicable for methods with return value.
  • exceptions: An array of GBCommentArgument objects. Only applicable for methods with exceptions.
  • crossrefs: An array of GBParagraphLinkItem 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 GBParsers who sets comments string value and GBProcessors 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

  • – registerParagraph: Registers the GBCommentParagraph and adds it to the end of paragraphs array.
  •   firstParagraph The first paragraph from paragraphs list or nil if no paragraph is registered. property
  •   paragraphs NSArray containing all paragraphs of the comment. property

Description paragraphs handling

Method arguments handling

  • – registerParameter: Registers the GBCommentArgument that describes a parameter and adds it to the end of parameters array.
  • – replaceParametersWithParametersFromArray: Replaces all registered parameters with the objects from the given array.
  • – registerResult: Registers the GBCommentParagraph that describes method return value.
  • – registerException: Registers the GBCommentArgument that describes an exception the method can raise and adds it to the end of exceptions array.
  • – registerCrossReference: Registers the GBParagraphLinkItem as an explicit, comment-wide, cross reference and adds it to the end of crossrefs array.
  •   parameters NSArray containing all method parameters described within the comment. property
  •   result The description of the method result or nil if this is not method comment or method has no result. property
  •   exceptions NSArray containing all exceptions commented method can raise as described within the comment. property
  •   crossrefs NSArray containing all explicit cross references as described within the comment. property

Output generator helpers

  •   hasParagraphs Indicates whether the comment has at least one paragraph or not. property
  •   hasDescriptionParagraphs Indicates whether the comment has at least two paragraphs or not. property
  •   hasParameters Indicates whether the comment has at least one parameter or not. property
  •   hasExceptions Indicates whether the comment has at least one exception or not. property
  •   hasCrossrefs Indicates whether the comment has at least one cross reference or not. property
  •   isCopied Specifies whether the comment is copied from another object or this is the original comment from source code. property

Input values

Properties

crossrefs

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

@property (readonly) NSArray *crossrefs

Discussion

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

descriptionParagraphs

NSArray containing all paragraphs that should be used for object description.

@property (readonly) NSArray *descriptionParagraphs

Discussion

The paragraphs are in the same order as in the source code. Each object is a GBCommentParagraph instance and should be registered through registerDescriptionParagraph: method. This array may be the same as paragraphs or it may be different, depending the application settings. It's up to client code to provide the description paragraphs!

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

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 value is automatically set when registering paragraphs, although it can be changed if needed. By default the value is set to the first paragraph registered.

See Also

Declared In

GBComment.h

hasCrossrefs

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

@property (readonly) BOOL hasCrossrefs

Discussion

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

hasDescriptionParagraphs

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

@property (readonly) BOOL hasDescriptionParagraphs

Discussion

This is used mainly to simplify template output generators. Programmatically this method is equal to testing whether descriptionParagraphs count is greater than 0, like this: [object.descriptionParagraphs 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

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

hasParagraphs

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

@property (readonly) BOOL hasParagraphs

Discussion

This is used mainly to simplify template output generators. Programmatically this method is equal to testing whether paragraphs 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

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

isCopied

Specifies whether the comment is copied from another object or this is the original comment from source code.

@property (assign) BOOL isCopied

Discussion

This flag is used to ignore unknown cross references warnings for comments copied from another object.

Declared In

GBComment.h

paragraphs

NSArray containing all paragraphs of the comment.

@property (readonly) NSArray *paragraphs

Discussion

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

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 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

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

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

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

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

registerDescriptionParagraph:

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

- (void)registerDescriptionParagraph:(GBCommentParagraph *)paragraph

Parameters

paragraph
Paragraph to register.

Discussion

If descriptionParagraphs is nil, a new array is created before adding the given object to it.

Exceptions

NSException
Thrown if the given paragraph 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

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

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

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

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

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