| Inherits from | NSObject |
| Declared in | GBComment.h<br />GBComment.m |
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.
+ commentWithStringValue:
Returns a new autoreleased instance of the comment with the given string value.
+ commentWithStringValue:sourceInfo:
Returns a new autoreleased instance of the comment with the given string value and source info.
- 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.
paragraphs
NSArray containing all paragraphs of the comment.
- 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.
result
The description of the method result or nil if this is not method comment or method has no result.
exceptions
NSArray containing all exceptions commented method can raise as described within the comment.
crossrefs
NSArray containing all explicit cross references as described within the comment.
hasParagraphs
Indicates whether the comment has at least one paragraph or not.
hasMultipleParagraphs
Indicates whether the comment has at least two paragraphs or not.
hasParameters
Indicates whether the comment has at least one parameter or not.
hasExceptions
Indicates whether the comment has at least one exception or not.
hasCrossrefs
Indicates whether the comment has at least one cross reference or not.
sourceInfo
Comment's source file info.
stringValue
Comment's raw string value as declared in source code.
Returns a new autoreleased instance of the comment with the given string value.
+ (id)commentWithStringValue:(NSString *)value Returns initialized object or nil if initialization fails.
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.
GBComment.hGBComment.mReturns a new autoreleased instance of the comment with the given string value and source info.
+ (id)commentWithStringValue:(NSString *)value sourceInfo:(GBSourceInfo *)info Returns initialized object or nil if initialization fails.
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.
GBComment.hGBComment.m Registers the GBParagraphLinkItem as an explicit, comment-wide, cross reference and adds it to the end of crossrefs array.
- (void)registerCrossReference:(GBParagraphLinkItem *)ref 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.
nil . GBComment.hGBComment.m Registers the GBCommentArgument that describes an exception the method can raise and adds it to the end of exceptions array.
- (void)registerException:(GBCommentArgument *)exception 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.
nil . GBComment.hGBComment.m Registers the GBCommentParagraph and adds it to the end of paragraphs array.
- (void)registerParagraph:(GBCommentParagraph *)paragraph 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!).
nil . GBComment.hGBComment.m Registers the GBCommentArgument that describes a parameter and adds it to the end of parameters array.
- (void)registerParameter:(GBCommentArgument *)parameter 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.
nil or [GBCommentArgument argumentName] is nil or empty string. GBComment.hGBComment.m Registers the GBCommentParagraph that describes method return value.
- (void)registerResult:(GBCommentParagraph *)result 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.
nil . GBComment.hGBComment.m Replaces all registered parameters with the objects from the given array.
- (void)replaceParametersWithParametersFromArray:(NSArray *)array 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.
GBComment.hGBComment.m NSArray containing all explicit cross references as described within the comment.
@property (readonly) NSArray *crossrefs 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.
GBComment.h NSArray containing all exceptions commented method can raise as described within the comment.
@property (readonly) NSArray *exceptions 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.
GBComment.h The first paragraph from paragraphs list or nil if no paragraph is registered.
@property (retain) GBCommentParagraph *firstParagraph 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.
GBComment.hIndicates whether the comment has at least one cross reference or not.
@property (readonly) BOOL hasCrossrefsIndicates 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 .
GBComment.hIndicates whether the comment has at least one exception or not.
@property (readonly) BOOL hasExceptionsIndicates 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 .
GBComment.hIndicates whether the comment has at least two paragraphs or not.
@property (readonly) BOOL hasMultipleParagraphsIndicates 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 .
GBComment.hIndicates whether the comment has at least one paragraph or not.
@property (readonly) BOOL hasParagraphsIndicates 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 .
GBComment.hIndicates whether the comment has at least one parameter or not.
@property (readonly) BOOL hasParametersIndicates 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 .
GBComment.h NSArray containing all paragraphs of the comment.
@property (readonly) NSArray *paragraphs 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.
GBComment.h NSArray containing all method parameters described within the comment.
@property (readonly) NSArray *parameters 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.
GBComment.h The description of the method result or nil if this is not method comment or method has no result.
@property (readonly, retain) GBCommentParagraph *result 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.
GBComment.h