Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Cleaned up source code.

  • Loading branch information...
commit 1ad2f9dee59ba3ccff499e1ec109770b81f93804 1 parent 6d03134
@tomaz authored
Showing with 86 additions and 5,910 deletions.
  1. +29 −29 Generating/GBDocSetOutputGenerator.m
  2. +0 −237 Model/GBComment.h
  3. +1 −190 Model/GBComment.m
  4. +0 −57 Model/GBCommentArgument.h
  5. +0 −46 Model/GBCommentArgument.m
  6. +0 −53 Model/GBCommentParagraph.h
  7. +0 −68 Model/GBCommentParagraph.m
  8. +0 −8 Model/GBDataObjects.h
  9. +0 −68 Model/GBParagraphDecoratorItem.h
  10. +0 −76 Model/GBParagraphDecoratorItem.m
  11. +0 −90 Model/GBParagraphItem.h
  12. +0 −87 Model/GBParagraphItem.m
  13. +0 −61 Model/GBParagraphLinkItem.h
  14. +0 −32 Model/GBParagraphLinkItem.m
  15. +0 −55 Model/GBParagraphListItem.h
  16. +0 −91 Model/GBParagraphListItem.m
  17. +0 −84 Model/GBParagraphSpecialItem.h
  18. +0 −77 Model/GBParagraphSpecialItem.m
  19. +0 −17 Model/GBParagraphTextItem.h
  20. +0 −21 Model/GBParagraphTextItem.m
  21. +16 −683 Processing/GBCommentsProcessor.m
  22. +39 −71 Processing/GBProcessor.m
  23. +0 −254 Testing/GBCommentTesting.m
  24. +0 −97 Testing/GBCommentsProcessor-BugsTesting.m
  25. +0 −92 Testing/GBCommentsProcessor-ComplexTesting.m
  26. +0 −420 Testing/GBCommentsProcessor-DecoratorItemsTesting.m
  27. +0 −202 Testing/GBCommentsProcessor-ExamplesTesting.m
  28. +0 −873 Testing/GBCommentsProcessor-LinkItemsTesting.m
  29. +0 −494 Testing/GBCommentsProcessor-MethodArgumentsTesting.m
  30. +0 −192 Testing/GBCommentsProcessor-OrderedListsTesting.m
  31. +0 −64 Testing/GBCommentsProcessor-TextItemsTesting.m
  32. +0 −179 Testing/GBCommentsProcessor-UnorderedListsTesting.m
  33. +0 −97 Testing/GBCommentsProcessor-WarningsTesting.m
  34. +0 −12 Testing/GBObjectsAssertor.h
  35. +0 −248 Testing/GBObjectsAssertor.m
  36. +0 −198 Testing/GBParagraphItemsTesting.m
  37. +1 −179 Testing/GBProcessor-CommentsTesting.m
  38. +0 −108 appledoc.xcodeproj/project.pbxproj
View
58 Generating/GBDocSetOutputGenerator.m
@@ -253,41 +253,41 @@ - (void)addTokensXmlModelObjectDataForObject:(GBModelBase *)object toData:(NSMut
[data setObject:[self tokenIdentifierForObject:object] forKey:@"identifier"];
[data setObject:[[object.sourceInfosSortedByName objectAtIndex:0] filename] forKey:@"declaredin"];
if (object.comment) {
- if (object.comment.hasParagraphs) [data setObject:object.comment.firstParagraph forKey:@"abstract"];
- if ([object.comment.crossrefs count] > 0) {
- NSMutableArray *related = [NSMutableArray arrayWithCapacity:[object.comment.crossrefs count]];
- for (GBParagraphLinkItem *crossref in object.comment.crossrefs) {
- if (crossref.member)
- [related addObject:[self tokenIdentifierForObject:crossref.member]];
- else if (crossref.context)
- [related addObject:[self tokenIdentifierForObject:crossref.context]];
- }
- if ([related count] > 0) {
- [data setObject:[GRYes yes] forKey:@"hasRelatedTokens"];
- [data setObject:related forKey:@"relatedTokens"];
- }
- }
+// if (object.comment.hasParagraphs) [data setObject:object.comment.firstParagraph forKey:@"abstract"];
+// if ([object.comment.crossrefs count] > 0) {
+// NSMutableArray *related = [NSMutableArray arrayWithCapacity:[object.comment.crossrefs count]];
+// for (GBParagraphLinkItem *crossref in object.comment.crossrefs) {
+// if (crossref.member)
+// [related addObject:[self tokenIdentifierForObject:crossref.member]];
+// else if (crossref.context)
+// [related addObject:[self tokenIdentifierForObject:crossref.context]];
+// }
+// if ([related count] > 0) {
+// [data setObject:[GRYes yes] forKey:@"hasRelatedTokens"];
+// [data setObject:related forKey:@"relatedTokens"];
+// }
+// }
}
if ([object isKindOfClass:[GBMethodData class]]) {
GBMethodData *method = (GBMethodData *)object;
[data setObject:method.formattedComponents forKey:@"formattedComponents"];
[data setObject:method.methodPrefix forKey:@"prefix"];
if (method.comment) {
- if (method.comment.hasParameters) {
- NSMutableArray *arguments = [NSMutableArray arrayWithCapacity:[method.comment.parameters count]];
- for (GBCommentArgument *argument in method.comment.parameters) {
- NSMutableDictionary *argData = [NSMutableDictionary dictionaryWithCapacity:2];
- [argData setObject:argument.argumentName forKey:@"name"];
- [argData setObject:argument.argumentDescription forKey:@"abstract"];
- [arguments addObject:argData];
- }
- [data setObject:arguments forKey:@"parameters"];
- [data setObject:[GRYes yes] forKey:@"hasParameters"];
- }
- if (method.comment.result) {
- NSDictionary *resultData = [NSDictionary dictionaryWithObject:method.comment.result forKey:@"abstract"];
- [data setObject:resultData forKey:@"returnValue"];
- }
+// if (method.comment.hasParameters) {
+// NSMutableArray *arguments = [NSMutableArray arrayWithCapacity:[method.comment.parameters count]];
+// for (GBCommentArgument *argument in method.comment.parameters) {
+// NSMutableDictionary *argData = [NSMutableDictionary dictionaryWithCapacity:2];
+// [argData setObject:argument.argumentName forKey:@"name"];
+// [argData setObject:argument.argumentDescription forKey:@"abstract"];
+// [arguments addObject:argData];
+// }
+// [data setObject:arguments forKey:@"parameters"];
+// [data setObject:[GRYes yes] forKey:@"hasParameters"];
+// }
+// if (method.comment.result) {
+// NSDictionary *resultData = [NSDictionary dictionaryWithObject:method.comment.result forKey:@"abstract"];
+// [data setObject:resultData forKey:@"returnValue"];
+// }
}
}
}
View
237 Model/GBComment.h
@@ -31,11 +31,6 @@
*/
@interface GBComment : NSObject {
@private
- NSMutableArray *_paragraphs;
- NSMutableArray *_descriptionParagraphs;
- NSMutableArray *_parameters;
- NSMutableArray *_exceptions;
- NSMutableArray *_crossrefs;
}
///---------------------------------------------------------------------------------------
@@ -64,241 +59,9 @@
+ (id)commentWithStringValue:(NSString *)value sourceInfo:(GBSourceInfo *)info;
///---------------------------------------------------------------------------------------
-/// @name Paragraphs handling
-///---------------------------------------------------------------------------------------
-
-/** 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!).
-
- @param paragraph Paragraph to register.
- @exception NSException Thrown if the given paragraph is `nil`.
- @see firstParagraph
- @see paragraphs
- */
-- (void)registerParagraph:(GBCommentParagraph *)paragraph;
-
-/** The first paragraph from `paragraphs` list or `nil` if no paragraph is registered.
-
- 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 registerParagraph:
- @see paragraphs
- @see shortDescription
- @see descriptionParagraphs
- */
-@property (retain) GBCommentParagraph *firstParagraph;
-
-/** Paragraph used for short description.
-
- This value is setup during post processing and represents object's short description. The difference between this and `firstParagraph` is that `firstParagraph` contains the whole of the first paragraph text, including potential special blocks such as warning, bug, lists, example etc. while `shortDescription` only contains text up to the first special block. This makes it much more suitable for using it as short description while generating output and it's in fact the reason for it's introduction.
-
- @see paragraphs
- @see descriptionParagraphs
- */
-@property (retain) GBCommentParagraph *shortDescription;
-
-/** `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 firstParagraph
- @see shortDescription
- @see descriptionParagraphs
- @see registerParagraph:
- @see parameters
- @see exceptions
- @see result
- */
-@property (readonly) NSArray *paragraphs;
-
-///---------------------------------------------------------------------------------------
-/// @name Description paragraphs handling
-///---------------------------------------------------------------------------------------
-
-/** Registers the `GBCommentParagraph` and adds it to the end of `descriptionParagraphs` array.
-
- If `descriptionParagraphs` is `nil`, a new array is created before adding the given object to it.
-
- @param paragraph Paragraph to register.
- @exception NSException Thrown if the given paragraph is `nil`.
- @see descriptionParagraphs
- @see registerParagraph:
- */
-- (void)registerDescriptionParagraph:(GBCommentParagraph *)paragraph;
-
-/** `NSArray` containing all paragraphs that should be used for object description.
-
- Description paragraph list's main purpose is to simplify templates. Depending the settings, the list either contains all paragraphs or excludes first one. This takes all guessing from templates and thus greatly simplifies it's work.
-
- 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 paragraphs
- @see hasDescriptionParagraphs
- @see registerDescriptionParagraph:
- */
-@property (readonly) NSArray *descriptionParagraphs;
-
-///---------------------------------------------------------------------------------------
-/// @name Method arguments handling
-///---------------------------------------------------------------------------------------
-
-/** 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.
-
- @param parameter Parameter to register.
- @exception NSException Thrown if the given parameter is `nil` or `[GBCommentArgument argumentName]` is `nil` or empty string.
- @see parameters
- @see replaceParametersWithParametersFromArray:
- @see registerResult:
- @see registerException:
- @see registerCrossReference:
- */
-- (void)registerParameter:(GBCommentArgument *)parameter;
-
-/** 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.
-
- @param array The array of parameters to register.
- @exception NSException Thrown if any of the objects is invalid, see registerParameter: for details.
- */
-- (void)replaceParametersWithParametersFromArray:(NSArray *)array;
-
-/** 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.
-
- @param result Result to register.
- @exception NSException Thrown if the given result is `nil`.
- @see result
- @see registerParameter:
- @see registerException:
- @see registerCrossReference:
- */
-- (void)registerResult:(GBCommentParagraph *)result;
-
-/** 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.
-
- @param exception Exception to register.
- @exception NSException Thrown if the given exception is `nil`.
- @see exceptions
- @see registerParameter:
- @see registerResult:
- @see registerCrossReference:
- */
-- (void)registerException:(GBCommentArgument *)exception;
-
-/** 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.
-
- @param ref The cross reference to register.
- @see crossrefs
- @see registerParameter:
- @see registerResult:
- @see registerException:
- @exception NSException Thrown if the given reference is `nil`.
- */
-- (void)registerCrossReference:(GBParagraphLinkItem *)ref;
-
-/** `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 registerParameter:
- @see exceptions
- @see result
- @see crossrefs
- @see paragraphs
- */
-@property (readonly) NSArray *parameters;
-
-/** 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 registerResult:
- @see parameters
- @see exceptions
- @see crossrefs
- @see paragraphs
- */
-@property (readonly,retain) GBCommentParagraph *result;
-
-/** `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 registerException:
- @see parameters
- @see result
- @see crossrefs
- @see paragraphs
- */
-@property (readonly) NSArray *exceptions;
-
-/** `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 registerCrossReference:
- @see parameters
- @see result
- @see exceptions
- @see paragraphs
- */
-@property (readonly) NSArray *crossrefs;
-
-///---------------------------------------------------------------------------------------
/// @name Output generator helpers
///---------------------------------------------------------------------------------------
-/** 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 `paragraphs` count is greater than 0, like this: `[object.paragraphs count] > 0`.
-
- @see hasDescriptionParagraphs
- @see paragraphs
- */
-@property (readonly) BOOL hasParagraphs;
-
-/** 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 `descriptionParagraphs` count is greater than 0, like this: `[object.descriptionParagraphs count] > 0`.
-
- @see hasParagraphs
- @see paragraphs
- */
-@property (readonly) BOOL hasDescriptionParagraphs;
-
-/** 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 parameters
- */
-@property (readonly) BOOL hasParameters;
-
-/** 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 exceptions
- */
-@property (readonly) BOOL hasExceptions;
-
-/** 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 exceptions
- */
-@property (readonly) BOOL hasCrossrefs;
-
/** Specifies whether the comment is copied from another object or this is the original comment from source code.
This flag is used to ignore unknown cross references warnings for comments copied from another object.
View
191 Model/GBComment.m
@@ -6,21 +6,8 @@
// Copyright (C) 2010, Gentle Bytes. All rights reserved.
//
-#import "GBCommentParagraph.h"
-#import "GBCommentArgument.h"
-#import "GBParagraphLinkItem.h"
#import "GBComment.h"
-@interface GBComment ()
-
-- (BOOL)replaceArgumentWithSameNameInList:(NSMutableArray *)list withArgument:(GBCommentArgument *)argument;
-- (NSUInteger)processedItemsCount;
-@property (readwrite,retain) GBCommentParagraph *result;
-
-@end
-
-#pragma mark -
-
@implementation GBComment
#pragma mark Initialization & disposal
@@ -36,124 +23,6 @@ + (id)commentWithStringValue:(NSString *)value sourceInfo:(GBSourceInfo *)info {
return result;
}
-#pragma mark Registration handling
-
-- (void)registerParagraph:(GBCommentParagraph *)paragraph {
- NSParameterAssert(paragraph != nil);
- GBLogDebug(@"Registering paragraph %@...", paragraph);
- if (!_paragraphs) {
- _paragraphs = [[NSMutableArray alloc] init];
- self.firstParagraph = paragraph;
- }
- [_paragraphs addObject:paragraph];
-}
-
-- (void)registerDescriptionParagraph:(GBCommentParagraph *)paragraph {
- NSParameterAssert(paragraph != nil);
- GBLogDebug(@"Registering description paragraph %@...", paragraph);
- if (!_descriptionParagraphs) {
- _descriptionParagraphs = [[NSMutableArray alloc] init];
- }
- [_descriptionParagraphs addObject:paragraph];
-}
-
-- (void)registerParameter:(GBCommentArgument *)parameter {
- NSParameterAssert(parameter != nil);
- NSParameterAssert([parameter.argumentName length] > 0);
- GBLogDebug(@"Registering parameter %@...", parameter);
- if (!_parameters) _parameters = [[NSMutableArray alloc] init];
- if ([self replaceArgumentWithSameNameInList:_parameters withArgument:parameter]) {
- GBLogWarn(@"%@: Parameter with name %@ is already registered, replacing existing!", self, parameter.argumentName);
- return;
- }
- [_parameters addObject:parameter];
-}
-
-- (void)replaceParametersWithParametersFromArray:(NSArray *)array {
- if ([_parameters count] == 0 && [array count] == 0) return;
- GBLogDebug(@"Replacing parameters with %ld objects...", [array count]);
- [_parameters removeAllObjects];
- [array enumerateObjectsUsingBlock:^(id obj, NSUInteger idx, BOOL *stop) {
- [self registerParameter:obj];
- }];
-}
-
-- (void)registerResult:(GBCommentParagraph *)value {
- NSParameterAssert(value != nil);
- GBLogDebug(@"Registering result %@...", value);
- if (self.result) GBLogWarn(@"%@: Result is already registered, replacing existing!", self);
- self.result = value;
-}
-
-- (void)registerException:(GBCommentArgument *)exception {
- NSParameterAssert(exception != nil);
- GBLogDebug(@"Registering exception %@...", exception);
- if (!_exceptions) _exceptions = [[NSMutableArray alloc] init];
- if ([self replaceArgumentWithSameNameInList:_exceptions withArgument:exception]) {
- GBLogWarn(@"%@: Exception with name %@ is already registered, replacing existing!", self, exception.argumentName);
- return;
- }
- [_exceptions addObject:exception];
-}
-
-- (void)registerCrossReference:(GBParagraphLinkItem *)ref {
- NSParameterAssert(ref != nil);
- GBLogDebug(@"Registering cross reference %@...", ref);
- if (!_crossrefs) _crossrefs = [[NSMutableArray alloc] init];
- for (NSUInteger i=0; i<[_crossrefs count]; i++) {
- GBParagraphLinkItem *existing = [_crossrefs objectAtIndex:i];
- if ([existing.stringValue isEqualToString:ref.stringValue]) {
- GBLogWarn(@"%@: %@ cross reference is already registered, ignoring!", self, ref.stringValue);
- return;
- }
- }
- [_crossrefs addObject:ref];
-}
-
-- (BOOL)hasResult {
- return (self.result != nil);
-}
-
-#pragma mark Helper methods
-
-- (BOOL)replaceArgumentWithSameNameInList:(NSMutableArray *)list withArgument:(GBCommentArgument *)argument {
- __block BOOL result = NO;
- [list enumerateObjectsUsingBlock:^(GBCommentArgument *existing, NSUInteger idx, BOOL *stop) {
- if ([existing.argumentName isEqualToString:argument.argumentName]) {
- [list replaceObjectAtIndex:idx withObject:argument];
- result = YES;
- *stop = YES;
- }
- }];
- return result;
-}
-
-- (NSUInteger)processedItemsCount {
- return [self.paragraphs count] + [self.parameters count] + [self.exceptions count] + [self.crossrefs count] + (self.result ? 1 : 0);
-}
-
-#pragma mark Output helper method
-
-- (BOOL)hasParagraphs {
- return ([self.paragraphs count] > 0);
-}
-
-- (BOOL)hasDescriptionParagraphs {
- return ([self.descriptionParagraphs count] > 0);
-}
-
-- (BOOL)hasParameters {
- return ([self.parameters count] > 0);
-}
-
-- (BOOL)hasExceptions {
- return ([self.exceptions count] > 0);
-}
-
-- (BOOL)hasCrossrefs {
- return ([self.crossrefs count] > 0);
-}
-
#pragma mark Overriden methods
- (NSString *)description {
@@ -161,69 +30,11 @@ - (NSString *)description {
}
- (NSString *)debugDescription {
- BOOL multiline = ([self processedItemsCount] > 1);
- NSMutableString *result = [NSMutableString stringWithFormat:@"%@", [self className]];
-
- // Paragraphs.
- if ([self.paragraphs count] > 0) {
- [result appendFormat:@"{p%@", multiline ? @"\n" : @" "];
- [self.paragraphs enumerateObjectsUsingBlock:^(id obj, NSUInteger idx, BOOL *stop) {
- [result appendString:[obj debugDescription]];
- if (idx < [self.paragraphs count]-1) [result appendString:@",\n"];
- }];
- [result appendFormat:@"%@}", multiline ? @"\n" : @" "];
- }
-
- // Parameters.
- if ([self.parameters count] > 0) {
- [result appendFormat:@"{par%@", multiline ? @"\n" : @" "];
- [self.parameters enumerateObjectsUsingBlock:^(id obj, NSUInteger idx, BOOL *stop) {
- [result appendString:[obj debugDescription]];
- if (idx < [self.parameters count]-1) [result appendString:@",\n"];
- }];
- [result appendFormat:@"%@}", multiline ? @"\n" : @" "];
- }
-
- // Result.
- if (self.result) {
- [result appendFormat:@"{ret%@", multiline ? @"\n" : @" "];
- [result appendString:[self.result debugDescription]];
- [result appendFormat:@"%@}", multiline ? @"\n" : @" "];
- }
-
- // Exceptions.
- if ([self.exceptions count] > 0) {
- [result appendFormat:@"{exc%@", multiline ? @"\n" : @" "];
- [self.exceptions enumerateObjectsUsingBlock:^(id obj, NSUInteger idx, BOOL *stop) {
- [result appendString:[obj debugDescription]];
- if (idx < [self.exceptions count]-1) [result appendString:@",\n"];
- }];
- [result appendFormat:@"%@}", multiline ? @"\n" : @" "];
- }
-
- // Cross references.
- if ([self.crossrefs count] > 0) {
- [result appendFormat:@"{ref%@", multiline ? @"\n" : @" "];
- [self.crossrefs enumerateObjectsUsingBlock:^(id obj, NSUInteger idx, BOOL *stop) {
- [result appendString:[obj debugDescription]];
- if (idx < [self.crossrefs count]-1) [result appendString:@",\n"];
- }];
- [result appendFormat:@"%@}", multiline ? @"\n" : @" "];
- }
-
- return result;
+ return [self description];
}
#pragma mark Properties
-@synthesize descriptionParagraphs = _descriptionParagraphs;
-@synthesize paragraphs = _paragraphs;
-@synthesize parameters = _parameters;
-@synthesize exceptions = _exceptions;
-@synthesize crossrefs = _crossrefs;
-@synthesize result;
-@synthesize firstParagraph;
-@synthesize shortDescription;
@synthesize sourceInfo;
@synthesize isCopied;
@synthesize stringValue;
View
57 Model/GBCommentArgument.h
@@ -1,57 +0,0 @@
-//
-// GBCommentArgument.h
-// appledoc
-//
-// Created by Tomaz Kragelj on 19.9.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import <Foundation/Foundation.h>
-
-@class GBCommentParagraph;
-
-/** Describes an argument of a `GBComment`.
-
- An argument is a named argument such as parameter or exception. It contains the argument (parameter or exception) name as `argumentName` and corresponding description in the form of `GBCommentParagraph` as `argumentDescription`.
- */
-@interface GBCommentArgument : NSObject
-
-///---------------------------------------------------------------------------------------
-/// @name Initialization & disposal
-///---------------------------------------------------------------------------------------
-
-/** Returns a new autoreleased argument with the given name and description.
-
- Sending this method is equivalent to:
-
- GBCommentArgument *argument = [[[GBCommentArgument alloc] init] autorelease];
- argument.argumentName = name;
- argument.argumentDescription = description;
-
- @param name The name of the argument.
- @param description Description of the argument.
- @return Returns initialized instance.
- @exception NSException Thrown if name is `nil` or empty string or description is `nil`.
- */
-+ (id)argumentWithName:(NSString *)name description:(GBCommentParagraph *)description;
-
-/** Returns a new autoreleased argument with no name and description. */
-+ (id)argument;
-
-///---------------------------------------------------------------------------------------
-/// @name Values
-///---------------------------------------------------------------------------------------
-
-/** The name of the argument.
-
- @see argumentDescription
- */
-@property (copy) NSString *argumentName;
-
-/** Description of the argument as `GBCommentParagraph`.
-
- @see argumentName
- */
-@property (retain) GBCommentParagraph *argumentDescription;
-
-@end
View
46 Model/GBCommentArgument.m
@@ -1,46 +0,0 @@
-//
-// GBCommentArgument.m
-// appledoc
-//
-// Created by Tomaz Kragelj on 19.9.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import "GBCommentParagraph.h"
-#import "GBCommentArgument.h"
-
-@implementation GBCommentArgument
-
-#pragma mark Initialization & disposal
-
-+ (id)argumentWithName:(NSString *)name description:(GBCommentParagraph *)description {
- NSParameterAssert(name != nil);
- NSParameterAssert([name length] > 0);
- NSParameterAssert(description != nil);
- GBCommentArgument *result = [self argument];
- result.argumentName = name;
- result.argumentDescription = description;
- return result;
-}
-
-+ (id)argument {
- GBCommentArgument *result = [[GBCommentArgument alloc] init];
- return result;
-}
-
-#pragma mark Overriden methods
-
-- (NSString *)description {
- return [NSString stringWithFormat:@"Argument %@", self.argumentName];
-}
-
-- (NSString *)debugDescription {
- return [NSString stringWithFormat:@"%@ %@{ %@ }", [self className], self.argumentName, self.argumentDescription];
-}
-
-#pragma mark Properties
-
-@synthesize argumentName;
-@synthesize argumentDescription;
-
-@end
View
53 Model/GBCommentParagraph.h
@@ -1,53 +0,0 @@
-//
-// GBCommentParagraph.h
-// appledoc
-//
-// Created by Tomaz Kragelj on 27.8.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import <Foundation/Foundation.h>
-
-@class GBParagraphItem;
-
-/** Describes a paragraph for a `GBComment`.
-
- A paragraph is simply an array of items. It can contain the following objects: `GBParagraphTextItem`, `GBParagraphDecoratorItem`, `GBParagraphLinkItem`, `GBParagraphListItem`, `GBParagraphSpecialItem`.
- */
-@interface GBCommentParagraph : NSObject {
- @private
- NSMutableArray *_items;
-}
-
-///---------------------------------------------------------------------------------------
-/// @name Initialization & disposal
-///---------------------------------------------------------------------------------------
-
-/** Returns autoreleased paragraph instance. */
-+ (id)paragraph;
-
-///---------------------------------------------------------------------------------------
-/// @name Paragraph values
-///---------------------------------------------------------------------------------------
-
-/** Registers the given paragraph item by adding it to the end of `items` list.
-
- @param item The item to register.
- @exception NSException Thrown if `nil` is passed.
- */
-- (void)registerItem:(GBParagraphItem *)item;
-
-/** The list of all paragraph items in the order of registration.
-
- Each object is a subclass of `GBParagraphItem`.
- */
-@property (readonly) NSArray *paragraphItems;
-
-///---------------------------------------------------------------------------------------
-/// @name Input values
-///---------------------------------------------------------------------------------------
-
-/** Paragraph's raw string value as declared in source code. */
-@property (readonly) NSString *stringValue;
-
-@end
View
68 Model/GBCommentParagraph.m
@@ -1,68 +0,0 @@
-//
-// GBCommentParagraph.m
-// appledoc
-//
-// Created by Tomaz Kragelj on 27.8.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import "GBParagraphItem.h"
-#import "GBCommentParagraph.h"
-
-@implementation GBCommentParagraph
-
-#pragma mark Initialization & disposal
-
-+ (id)paragraph {
- return [[[self alloc] init] autorelease];
-}
-
-- (id)init {
- self = [super init];
- if (self) {
- _items = [[NSMutableArray alloc] init];
- }
- return self;
-}
-
-#pragma mark Items handling
-
-- (void)registerItem:(GBParagraphItem *)item {
- NSParameterAssert(item != nil);
- GBLogDebug(@"%@: Registering %@...", self, item);
- [_items addObject:item];
-}
-
-#pragma mark Overriden methods
-
-- (NSString *)description {
- NSString *desc = [self.stringValue length] > 0 ? [self.stringValue normalizedDescription] : @"";
- return [NSString stringWithFormat:@"Paragraph '%@'", desc];
-}
-
-- (NSString *)debugDescription {
- NSMutableString *result = [NSMutableString stringWithFormat:@"%@{ ", [self className]];
- if ([self.paragraphItems count] > 1) [result appendString:@"\n"];
- [self.paragraphItems enumerateObjectsUsingBlock:^(id obj, NSUInteger idx, BOOL *stop) {
- [result appendString:[obj debugDescription]];
- if (idx < [self.paragraphItems count]-1) [result appendString:@",\n"];
- }];
- [result appendString:([self.paragraphItems count] > 1) ? @"\n}" : @" }"];
- return result;
-}
-
-#pragma mark Properties
-
-- (NSString *)stringValue {
- NSMutableString *result = [NSMutableString stringWithCapacity:1000];
- for (GBParagraphItem *item in self.paragraphItems) {
- NSString *string = [item stringValue];
- if (item != [self.paragraphItems lastObject] && ![string hasSuffix:@"\n"]) string = [string stringByAppendingString:@"\n"];
- [result appendString:string];
- }
- return result;
-}
-
-@synthesize paragraphItems = _items;
-
-@end
View
8 Model/GBDataObjects.h
@@ -7,14 +7,6 @@
//
#import "GBComment.h"
-#import "GBCommentArgument.h"
-#import "GBCommentParagraph.h"
-#import "GBParagraphItem.h"
-#import "GBParagraphTextItem.h"
-#import "GBParagraphListItem.h"
-#import "GBParagraphSpecialItem.h"
-#import "GBParagraphDecoratorItem.h"
-#import "GBParagraphLinkItem.h"
#import "GBClassData.h"
#import "GBCategoryData.h"
View
68 Model/GBParagraphDecoratorItem.h
@@ -1,68 +0,0 @@
-//
-// GBParagraphDecoratorItem.h
-// appledoc
-//
-// Created by Tomaz Kragelj on 2.9.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import "GBParagraphItem.h"
-
-/** Specifies different decoration types of `GBParagraphDecoratorItem`s. */
-enum {
- /** The `GBParagraphDecoratorItem`s decorated item should be bold. */
- GBDecorationTypeBold,
- /** The `GBParagraphDecoratorItem`s decorated item should be italics. */
- GBDecorationTypeItalics,
- /** The `GBParagraphDecoratorItem`s decorated item should be code. */
- GBDecorationTypeCode,
-};
-typedef NSUInteger GBDecorationType;
-
-#pragma mark -
-
-/** Specifies a decorator paragraph item.
-
- Decorator items wrap an array of `GBParagraphItem` and speficies a decoration to be applied over them. Use `decorationType` to determine the type of decoration and `decoratedItems` to get the array of item to be decorated.
- */
-@interface GBParagraphDecoratorItem : GBParagraphItem {
- @private
- NSMutableArray *_decoratedItems;
-}
-
-///---------------------------------------------------------------------------------------
-/// @name Item handling
-///---------------------------------------------------------------------------------------
-
-/** Registers the given item to the end of `decoratedItems` array.
-
- @param item The item to register.
- @exception NSException Thrown if the given item is `nil`.
- @see replaceItemsByRegisteringItemsFromArray:
- */
-- (void)registerItem:(GBParagraphItem *)item;
-
-/** Replaces the `decoratedItems` array with the objects from the given array.
-
- @param items The array of `GBParagraphItem` instances to register.
- @see registerItem:
- */
-- (void)replaceItemsByRegisteringItemsFromArray:(NSArray *)items;
-
-///---------------------------------------------------------------------------------------
-/// @name Values
-///---------------------------------------------------------------------------------------
-
-/** The type of decoration to apply over assigned `decoratedItems`. */
-@property (assign) GBDecorationType decorationType;
-
-/** The `GBParagraphItem` instances we're decorating.
-
- Items can be registered through `registerItem:` or `registerItems:` methods.
-
- @see registerItem:
- @see replaceItemsByRegisteringItemsFromArray:
- */
-@property (readonly) NSArray *decoratedItems;
-
-@end
View
76 Model/GBParagraphDecoratorItem.m
@@ -1,76 +0,0 @@
-//
-// GBParagraphDecoratorItem.m
-// appledoc
-//
-// Created by Tomaz Kragelj on 2.9.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import "GBParagraphDecoratorItem.h"
-
-@implementation GBParagraphDecoratorItem
-
-#pragma mark Initialization & disposal
-
-- (id)init {
- self = [super init];
- if (self) {
- _decoratedItems = [NSMutableArray array];
- }
- return self;
-}
-
-#pragma mark Registrations handling
-
-- (void)registerItem:(GBParagraphItem *)item {
- NSParameterAssert(item != nil);
- GBLogDebug(@"%@: Registering %@...", self, item);
- [_decoratedItems addObject:item];
-}
-
-- (void)replaceItemsByRegisteringItemsFromArray:(NSArray *)items {
- if (!items || [items count] == 0) return;
- GBLogDebug(@"%@: Replacing items with %ld items...", self, [items count]);
- [_decoratedItems removeAllObjects];
- [items enumerateObjectsUsingBlock:^(id obj, NSUInteger idx, BOOL *stop) {
- [self registerItem:obj];
- }];
-}
-
-#pragma mark Overriden methods
-
-- (NSString *)descriptionStringValue {
- NSMutableString *result = [NSMutableString stringWithFormat:@"%@{", [super descriptionStringValue]];
- if ([self.decoratedItems count] > 1) [result appendString:@"\n"];
- [self.decoratedItems enumerateObjectsUsingBlock:^(id obj, NSUInteger idx, BOOL *stop) {
- [result appendString:[obj description]];
- if (idx < [self.decoratedItems count]-1) [result appendString:@",\n"];
- }];
- [result appendString:([self.decoratedItems count] > 1) ? @"\n}" : @" }"];
- return result;
-}
-
-- (NSString *)description {
- return [NSString stringWithFormat:@"Decorator '%@'", [super description]];
-}
-
-#pragma mark Helper methods
-
-- (BOOL)isBoldDecoratorItem {
- return (self.decorationType == GBDecorationTypeBold);
-}
-
-- (BOOL)isItalicsDecoratorItem {
- return (self.decorationType == GBDecorationTypeItalics);
-}
-
-- (BOOL)isCodeDecoratorItem {
- return (self.decorationType == GBDecorationTypeCode);
-}
-
-#pragma mark Properties
-
-@synthesize decoratedItems = _decoratedItems;
-@synthesize decorationType;
-
-@end
View
90 Model/GBParagraphItem.h
@@ -1,90 +0,0 @@
-//
-// GBParagraphItem.h
-// appledoc
-//
-// Created by Tomaz Kragelj on 30.8.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import <Foundation/Foundation.h>
-
-/** Defines the base functionality for all paragraph items.
- */
-@interface GBParagraphItem : NSObject
-
-///---------------------------------------------------------------------------------------
-/// @name Initialization & disposal
-///---------------------------------------------------------------------------------------
-
-/** Returns new autoreleased instance. */
-+ (id)paragraphItem;
-
-/** Returns new autoreleased instance with `stringValue` set to the given text.
-
- This is equivalent to the following code:
-
- GBParagraphItem *item = [GBParagraphItem paragraphItem];
- item.stringValue = value;
-
- @param value The string value of the item.
- @return Returns initialized value.
- */
-+ (id)paragraphItemWithStringValue:(NSString *)value;
-
-///---------------------------------------------------------------------------------------
-/// @name Values
-///---------------------------------------------------------------------------------------
-
-/** Item's string value.
-
- String value is used for output generation in case of leaf items. For container items, string value should not be used for output generation unless specified otherwise!
- */
-@property (copy) NSString *stringValue;
-
-///---------------------------------------------------------------------------------------
-/// @name Debugging aids
-///---------------------------------------------------------------------------------------
-
-/** String value as used in debug description.
-
- By default this returns string value trimmed to a predefined maximum length, but subclasses can override to provide their specific implementation. This is only used for debugging purposes and should not be used for any output generation! See `description` method implementation for details.
-
- Sending this message is equivalent to sending `descriptionForStringValue:` to receiver and passing it `stringValue` as the parameter.
- */
-@property (readonly) NSString *descriptionStringValue;
-
-///---------------------------------------------------------------------------------------
-/// @name Output generator helpers
-///---------------------------------------------------------------------------------------
-
-/** Returns `YES` if this item is text. This is only used to simplify output generation! */
-@property (readonly) BOOL isTextItem;
-
-/** Returns `YES` if this is ordered list item. This is only used to simplify output generation! */
-@property (readonly) BOOL isOrderedListItem;
-
-/** Returns `YES` if this is unordered list item. This is only used to simplify output generation! */
-@property (readonly) BOOL isUnorderedListItem;
-
-/** Returns `YES` if this is warning special item. This is only used to simplify output generation! */
-@property (readonly) BOOL isWarningSpecialItem;
-
-/** Returns `YES` if this is bug special item. This is only used to simplify output generation! */
-@property (readonly) BOOL isBugSpecialItem;
-
-/** Returns `YES` if this is example special item. This is only used to simplify output generation! */
-@property (readonly) BOOL isExampleSpecialItem;
-
-/** Returns `YES` if this is bold decorator item. This is only used to simplify output generation! */
-@property (readonly) BOOL isBoldDecoratorItem;
-
-/** Returns `YES` if this is italics decorator item. This is only used to simplify output generation! */
-@property (readonly) BOOL isItalicsDecoratorItem;
-
-/** Returns `YES` if this is code decorator item. This is only used to simplify output generation! */
-@property (readonly) BOOL isCodeDecoratorItem;
-
-/** Returns `YES` if this is link item. This is only used to simplify output generation! */
-@property (readonly) BOOL isLinkItem;
-
-@end
View
87 Model/GBParagraphItem.m
@@ -1,87 +0,0 @@
-//
-// GBParagraphItem.m
-// appledoc
-//
-// Created by Tomaz Kragelj on 30.8.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import "RegexKitLite.h"
-#import "GBParagraphItem.h"
-
-@implementation GBParagraphItem
-
-#pragma mark Initialization & disposal
-
-+ (id)paragraphItem {
- return [[[self alloc] init] autorelease];
-}
-
-+ (id)paragraphItemWithStringValue:(NSString *)value {
- GBParagraphItem *result = [self paragraphItem];
- result.stringValue = value;
- return result;
-}
-
-#pragma mark Overriden methods
-
-- (NSString *)description {
- if (!self.stringValue) return @"";
- return [self.stringValue normalizedDescription];
-}
-
-- (NSString *)debugDescription {
- return [NSString stringWithFormat:@"%@ '%@'", [self className], [self descriptionStringValue]];
-}
-
-- (NSString *)descriptionStringValue {
- return [NSString stringWithFormat:@"%@", [self.stringValue normalizedDescription]];
-}
-
-#pragma mark Output generator helpers
-
-- (BOOL)isTextItem {
- return NO;
-}
-
-- (BOOL)isOrderedListItem {
- return NO;
-}
-
-- (BOOL)isUnorderedListItem {
- return NO;
-}
-
-- (BOOL)isWarningSpecialItem {
- return NO;
-}
-
-- (BOOL)isBugSpecialItem {
- return NO;
-}
-
-- (BOOL)isExampleSpecialItem {
- return NO;
-}
-
-- (BOOL)isBoldDecoratorItem {
- return NO;
-}
-
-- (BOOL)isItalicsDecoratorItem {
- return NO;
-}
-
-- (BOOL)isCodeDecoratorItem {
- return NO;
-}
-
-- (BOOL)isLinkItem {
- return NO;
-}
-
-#pragma mark Properties
-
-@synthesize stringValue;
-
-@end
View
61 Model/GBParagraphLinkItem.h
@@ -1,61 +0,0 @@
-//
-// GBParagraphLinkItem.h
-// appledoc
-//
-// Created by Tomaz Kragelj on 7.9.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import "GBParagraphItem.h"
-
-@protocol GBObjectDataProviding;
-
-/** Specifies a link paragraph item.
-
- Link items wrap a cross reference link with all the data. There are several types of links:
-
- - Link to a URL: Points to a http, ftp or file objects. `stringValue` value represents the link value, while all other properties are `nil`. `isLocal` is `NO`.
- - Link to an object: Points to a known top-level object. `stringValue` value represents nicely formatted object's name and `context` points to the object instance while all other properties are `nil` and `isLocal` is either `YES` if the link's origin is the same object or `NO` if it's a link to another object.
- - Link to a local member: Points to another member of the same known top-level object. `stringValue` value represents nicely formatted link value, `context` points to the object instance and `member` to the object's member instance. `isLocal` value is `YES`.
- - Link to a member of another object: Points to a member of another object. Values representation is the same as in previous option, only `isLocal` value is `NO` in this case.
- */
-@interface GBParagraphLinkItem : GBParagraphItem
-
-///---------------------------------------------------------------------------------------
-/// @name Values
-///---------------------------------------------------------------------------------------
-
-/** The href value to which the link "points" to.
-
- This can actually be used when generating output to get proper URL of the link item.
- */
-@property (retain) NSString *href;
-
-/** The context to which the link's `member` points to or `nil` if this is a `stringValue` link.
-
- The context can be either `GBClassData`, `GBCategoryData` or `GBProtocolData` if provided.
-
- @see member
- @see isLocal
- */
-@property (retain) id context;
-
-/** The member to which the link points to or `nil` if this is either a `stringValue` link or `context` link.
-
- This is only used if the link points to a `member` within a `context`. If this is link to the `context` itself or to an `stringValue`, this value is `nil`. The member can only be a `GBMethodData` instance at this point.
-
- @see context
- @see isLocal
- */
-@property (retain) id member;
-
-/** Specifies whether the link is local or not.
-
- If a link is local, it points from within a `context` either to the `context` itself (i.e. `member` is `nil`) or to on eof the the same `context`s members. If the link points to another `context` or to one of other `context`s `member`, or this is a `stringValue` link, the value is `NO`.
-
- @see context
- @see member
- */
-@property (assign) BOOL isLocal;
-
-@end
View
32 Model/GBParagraphLinkItem.m
@@ -1,32 +0,0 @@
-//
-// GBParagraphLinkItem.m
-// appledoc
-//
-// Created by Tomaz Kragelj on 7.9.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import "GBParagraphLinkItem.h"
-
-@implementation GBParagraphLinkItem
-
-#pragma mark Overriden methods
-
-- (NSString *)description {
- return [NSString stringWithFormat:@"Link '%@'", [super description]];
-}
-
-#pragma mark Helper methods
-
-- (BOOL)isLinkItem {
- return YES;
-}
-
-#pragma mark Properties
-
-@synthesize href;
-@synthesize context;
-@synthesize member;
-@synthesize isLocal;
-
-@end
View
55 Model/GBParagraphListItem.h
@@ -1,55 +0,0 @@
-//
-// GBParagraphListItem.h
-// appledoc
-//
-// Created by Tomaz Kragelj on 31.8.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import "GBParagraphItem.h"
-
-@class GBCommentParagraph;
-
-/** Handles ordered and unordered lists for a `GBCommentParagraph`.
-
- Lists are containers for list items which are instances of `GBCommentParagraph`. This allows us to form a tree structure with nested lists and other paragraph items. Lists can be ordered or unordered, the type can be determined by testing the value of `isOrdered` property.
- */
-@interface GBParagraphListItem : GBParagraphItem {
- @private
- NSMutableArray *_items;
-}
-
-///---------------------------------------------------------------------------------------
-/// @name Initialization & disposal
-///---------------------------------------------------------------------------------------
-
-/** Returns new autoreleased list item with `ordered` set to `YES`.
-
- This is equivalent to initializing with designated initialized (`init`) and setting `ordered` property value of initializaed object to `YES`.
- */
-+ (id)orderedParagraphListItem;
-
-/** Returns new autoreleased list item with `ordered` set to `NO`.
-
- This is equivalent to initializing with designated initialized (`init`) and setting `ordered` property value of initializaed object to `NO`.
- */
-+ (id)unorderedParagraphListItem;
-
-///---------------------------------------------------------------------------------------
-/// @name Values
-///---------------------------------------------------------------------------------------
-
-/** Registers the given item by adding it to the end of `items` array.
-
- @param item `GBCommentParagraph` to register.
- @exception NSException Thrown if the given item is `nil`.
- */
-- (void)registerItem:(GBCommentParagraph *)item;
-
-/** Specifies whether the list is ordered (`YES`) or unordered (`NO`). */
-@property (assign) BOOL isOrdered;
-
-/** Array of all list items as instances of `GBCommentParagraph` in the same order as in comment text. */
-@property (readonly) NSArray *listItems;
-
-@end
View
91 Model/GBParagraphListItem.m
@@ -1,91 +0,0 @@
-//
-// GBParagraphListItem.m
-// appledoc
-//
-// Created by Tomaz Kragelj on 31.8.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import "GBParagraphListItem.h"
-
-@interface GBParagraphListItem ()
-
-+ (id)newParagraphListItemWithOrderedValue:(BOOL)ordered;
-
-@end
-
-#pragma mark -
-
-@implementation GBParagraphListItem
-
-#pragma mark Initialization & disposal
-
-+ (id)orderedParagraphListItem {
- return [self newParagraphListItemWithOrderedValue:YES];
-}
-
-+ (id)unorderedParagraphListItem {
- return [self newParagraphListItemWithOrderedValue:NO];
-}
-
-+ (id)newParagraphListItemWithOrderedValue:(BOOL)ordered {
- GBParagraphListItem *result = [[[self alloc] init] autorelease];
- result.isOrdered = ordered;
- return result;
-}
-
-- (id)init {
- self = [super init];
- if (self) {
- _items = [[NSMutableArray alloc] init];
- }
- return self;
-}
-
-#pragma mark Helper methods
-
-- (void)registerItem:(GBCommentParagraph *)item {
- NSParameterAssert(item != nil);
- GBLogDebug(@"%@: Registering %@...", self, item);
- [_items addObject:item];
-}
-
-- (BOOL)isOrderedListItem {
- return self.isOrdered;
-}
-
-- (BOOL)isUnorderedListItem {
- return !self.isOrdered;
-}
-
-#pragma mark Overriden methods
-
-- (NSString *)stringValue {
- NSMutableString *description = [NSMutableString stringWithCapacity:1000];
- [self.listItems enumerateObjectsUsingBlock:^(GBCommentParagraph *paragraph, NSUInteger idx, BOOL *stop) {
- [description appendFormat:@"%@ %@ ", self.isOrdered ? @"#" : @"-", [paragraph stringValue]];
- }];
- return [description stringByTrimmingWhitespaceAndNewLine];
-}
-
-- (NSString *)descriptionStringValue {
- NSMutableString *result = [NSMutableString stringWithFormat:@"%@{ ", [super descriptionStringValue]];
- if ([self.listItems count] > 1) [result appendString:@"\n"];
- [self.listItems enumerateObjectsUsingBlock:^(id obj, NSUInteger idx, BOOL *stop) {
- [result appendString:[obj description]];
- if (idx < [self.listItems count]-1) [result appendString:@",\n"];
- }];
- [result appendString:([self.listItems count] > 1) ? @"\n}" : @" }"];
- return result;
-}
-
-- (NSString *)description {
- return [NSString stringWithFormat:@"List '%@'", [super description]];
-}
-
-#pragma mark Properties
-
-@synthesize listItems = _items;
-@synthesize isOrdered;
-
-@end
View
84 Model/GBParagraphSpecialItem.h
@@ -1,84 +0,0 @@
-//
-// GBParagraphSpecialItem.h
-// appledoc
-//
-// Created by Tomaz Kragelj on 1.9.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import "GBParagraphItem.h"
-
-@class GBCommentParagraph;
-
-/** Defines different `GBParagraphSpecialItem` types. */
-enum {
- /** The `GBParagraphSpecialItem` represents a warning. */
- GBSpecialItemTypeWarning,
- /** The `GBParagraphSpecialItem` represents a bug. */
- GBSpecialItemTypeBug,
- /** The `GBParagraphSpecialItem` represents an example section. */
- GBSpecialItemTypeExample,
-};
-typedef NSUInteger GBSpecialItemType;
-
-#pragma mark -
-
-/** Handles special paragraph items such as warnings and bugs.
-
- Special items are containers for `GBCommentParagraph` which are formatted differently to catch user's attention. There can be several types of special items, to determine the type, use the value of `specialItemType` property.
- */
-@interface GBParagraphSpecialItem : GBParagraphItem {
- @private
- GBCommentParagraph *_specialItemDescription;
-}
-
-///---------------------------------------------------------------------------------------
-/// @name Initialization & disposal
-///---------------------------------------------------------------------------------------
-
-/** Returns new autoreleased `GBParagraphSpecialItem` instance of te given type.
-
- Sending this message to the class is equivalent of:
-
- GBParagraphSpecialItem *item = [[[GBParagraphSpecialItem alloc] init] autorelease];
- item.specialItemType = type;
-
- @param type The type of the special item.
- @return Returns initialized instance.
- @see specialItemWithType:stringValue:
- */
-+ (id)specialItemWithType:(GBSpecialItemType)type;
-
-/** Returns new autoreleased `GBParagraphSpecialItem` instance of te given type.
-
- Sending this message to the class is equivalent of:
-
- GBParagraphSpecialItem *item = [[[GBParagraphSpecialItem alloc] init] autorelease];
- item.specialItemType = type;
- item.stringValue = value;
-
- @param type The type of the special item.
- @param value The desired string value.
- @return Returns initialized instance.
- @see specialItemWithType:
- */
-+ (id)specialItemWithType:(GBSpecialItemType)type stringValue:(NSString *)value;
-
-///---------------------------------------------------------------------------------------
-/// @name Values
-///---------------------------------------------------------------------------------------
-
-/** Registers the given paragraph.
-
- @param paragraph `GBCommentParagraph` to register.
- @exception NSException Thrown if the given item is `nil`.
- */
-- (void)registerParagraph:(GBCommentParagraph *)paragraph;
-
-/** The description of the special item in the form of `GBCommentParagraph`. */
-@property (readonly) GBCommentParagraph *specialItemDescription;
-
-/** The type of the special item. */
-@property (assign) GBSpecialItemType specialItemType;
-
-@end
View
77 Model/GBParagraphSpecialItem.m
@@ -1,77 +0,0 @@
-//
-// GBParagraphSpecialItem.m
-// appledoc
-//
-// Created by Tomaz Kragelj on 1.9.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import "GBCommentParagraph.h"
-#import "GBParagraphSpecialItem.h"
-
-@implementation GBParagraphSpecialItem
-
-#pragma mark Initialization & disposal
-
-+ (id)specialItemWithType:(GBSpecialItemType)type {
- return [self specialItemWithType:type stringValue:nil];
-}
-
-+ (id)specialItemWithType:(GBSpecialItemType)type stringValue:(NSString *)value {
- GBParagraphSpecialItem *result = [[[self alloc] init] autorelease];
- result.specialItemType = type;
- result.stringValue = value;
- return result;
-}
-
-#pragma mark Helper methods
-
-- (void)registerParagraph:(GBCommentParagraph *)paragraph {
- NSParameterAssert(paragraph != nil);
- GBLogDebug(@"%@: Registering %@...", self, paragraph);
- _specialItemDescription = [paragraph retain];
-}
-
-- (BOOL)isWarningSpecialItem {
- return (self.specialItemType == GBSpecialItemTypeWarning);
-}
-
-- (BOOL)isBugSpecialItem {
- return (self.specialItemType == GBSpecialItemTypeBug);
-}
-
-- (BOOL)isExampleSpecialItem {
- return (self.specialItemType == GBSpecialItemTypeExample);
-}
-
-#pragma mark Overriden methods
-
-- (NSString *)descriptionStringValue {
- return [NSString stringWithFormat:@"%@{ %@ }", [super descriptionStringValue], self.specialItemDescription];
-}
-
-- (NSString *)description {
- NSString *type = nil;
- switch (self.specialItemType) {
- case GBSpecialItemTypeWarning:
- type = @"Warning";
- break;
- case GBSpecialItemTypeBug:
- type = @"Bug";
- break;
- case GBSpecialItemTypeExample:
- type = @"Example";
- break;
- default:
- type = @"Special";
- break;
- }
- return [NSString stringWithFormat:@"%@ '%@'", type, [super description]];
-}
-
-#pragma mark Properties
-
-@synthesize specialItemDescription = _specialItemDescription;
-@synthesize specialItemType;
-
-@end
View
17 Model/GBParagraphTextItem.h
@@ -1,17 +0,0 @@
-//
-// GBParagraphTextItem.h
-// appledoc
-//
-// Created by Tomaz Kragelj on 31.8.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import "GBParagraphItem.h"
-
-/** Handles normal or formatted text for a `GBCommentParagraph`.
-
- Use `stringValue` to get the text value of the item.
- */
-@interface GBParagraphTextItem : GBParagraphItem
-
-@end
View
21 Model/GBParagraphTextItem.m
@@ -1,21 +0,0 @@
-//
-// GBParagraphTextItem.m
-// appledoc
-//
-// Created by Tomaz Kragelj on 31.8.10.
-// Copyright (C) 2010, Gentle Bytes. All rights reserved.
-//
-
-#import "GBParagraphTextItem.h"
-
-@implementation GBParagraphTextItem
-
-- (NSString *)description {
- return [NSString stringWithFormat:@"Text '%@'", [super description]];
-}
-
-- (BOOL)isTextItem {
- return YES;
-}
-
-@end
View
699 Processing/GBCommentsProcessor.m
@@ -14,39 +14,12 @@
@interface GBCommentsProcessor ()
+- (BOOL)isLineMatchingDirectiveStatement:(NSString *)string;
- (BOOL)findCommentBlockInLines:(NSArray *)lines blockRange:(NSRange *)range;
- (void)processCommentBlockInLines:(NSArray *)lines blockRange:(NSRange)range;
-- (BOOL)registerWarningBlockFromlines:(NSArray *)lines;
-- (BOOL)registerBugBlockFromLines:(NSArray *)lines;
-- (BOOL)registerExampleBlockFromLines:(NSArray *)lines;
-- (BOOL)registerListBlockFromLines:(NSArray *)lines;
-- (BOOL)registerDirectivesBlockFromLines:(NSArray *)lines;
-- (void)registerTextBlockFromLines:(NSArray *)lines;
-- (BOOL)isLineMatchingDirectiveStatement:(NSString *)string;
-
-- (void)registerTextItemsFromStringToCurrentParagraph:(NSString *)string;
-- (void)registerTextAndLinkItemsFromString:(NSString *)string toObject:(id)object;
-
-- (id)linkItemFromString:(NSString *)string range:(NSRange *)range description:(NSString **)description templated:(BOOL)templated;
-- (id)remoteMemberLinkItemFromString:(NSString *)string range:(NSRange *)range templated:(BOOL)templated;
-- (id)localMemberLinkFromString:(NSString *)string range:(NSRange *)range templated:(BOOL)templated;
-- (id)classLinkFromString:(NSString *)string range:(NSRange *)range templated:(BOOL)templated;
-- (id)categoryLinkFromString:(NSString *)string range:(NSRange *)range templated:(BOOL)templated;
-- (id)protocolLinkFromString:(NSString *)string range:(NSRange *)range templated:(BOOL)templated;
-- (id)documentLinkFromString:(NSString *)string range:(NSRange *)range templated:(BOOL)templated;
-- (id)urlLinkItemFromString:(NSString *)string range:(NSRange *)range templated:(BOOL)templated;
-
-- (GBCommentParagraph *)pushParagraphIfStackIsEmpty;
-- (GBCommentParagraph *)pushParagraph:(BOOL)canAutoRegister;
-- (GBCommentParagraph *)peekParagraph;
-- (GBCommentParagraph *)popParagraph;
-- (void)popAllParagraphs;
-
-@property (retain) NSMutableArray *paragraphsStack;
-@property (retain) GBComment *currentComment;
@property (retain) id currentContext;
-
+@property (retain) GBComment *currentComment;
@property (retain) GBStore *store;
@property (retain) GBApplicationSettingsProvider *settings;
@property (readonly) GBCommentComponentsProvider *components;
@@ -86,7 +59,6 @@ - (void)processComment:(GBComment *)comment withContext:(id<GBObjectDataProvidin
NSParameterAssert(comment != nil);
NSParameterAssert(store != nil);
GBLogDebug(@"Processing %@ found in %@...", comment, comment.sourceInfo.filename);
- self.paragraphsStack = [NSMutableArray array];
self.currentComment = comment;
self.currentContext = context;
self.store = store;
@@ -99,7 +71,6 @@ - (void)processComment:(GBComment *)comment withContext:(id<GBObjectDataProvidin
[self processCommentBlockInLines:lines blockRange:range];
range.location += range.length;
}
- [self popAllParagraphs];
}
- (BOOL)findCommentBlockInLines:(NSArray *)lines blockRange:(NSRange *)range {
@@ -135,314 +106,20 @@ - (BOOL)findCommentBlockInLines:(NSArray *)lines blockRange:(NSRange *)range {
}
- (void)processCommentBlockInLines:(NSArray *)lines blockRange:(NSRange)range {
- // The given range is guaranteed to point to actual block within the lines array, so we only need to determine the kind of block and how to handle it.
- NSArray *block = [lines subarrayWithRange:range];
- self.currentStartLine = self.currentComment.sourceInfo.lineNumber + range.location;
-
- // If the block defines one of the known paragraph items, register it and return. Note that paragraph items are simply added to previous paragraph, however if no paragraph exists yet, this will automatically create one.
- if ([self registerExampleBlockFromLines:block]) return;
- if ([self registerBugBlockFromLines:block]) return;
- if ([self registerWarningBlockFromlines:block]) return;
- if ([self registerListBlockFromLines:block]) return;
- if ([self registerDirectivesBlockFromLines:block]) return;
-
- // If nothing else is matched, the block is standard text. For that we need to start a new paragraph and process the text. Note that we first need to close all open paragraphs - even if the paragraph was started by a known paragraph item block, new text block always starts a new paragraph at this point. But we must keep the new paragraph open in case next block defines an item.
- [self popAllParagraphs];
- [self registerTextBlockFromLines:block];
-}
-
-#pragma mark Comment blocks processing
-
-- (BOOL)registerWarningBlockFromlines:(NSArray *)lines {
- // Warning block is a GBParagraphSpecialItem containing one or more GBParagraph items.
- NSString *regex = self.components.warningSectionRegex;
- if (![[lines firstObject] isMatchedByRegex:regex]) return NO;
-
- // Get the description and warn if empty text was found (we still return YES as the block was properly detected as @warning.
- NSString *string = [NSString stringByCombiningLines:lines delimitWith:@"\n"];
- NSString *description = [string stringByMatching:regex capture:1];
- if ([description length] == 0) {
- if (self.settings.warnOnEmptyDescription) GBLogWarn(@"Empty @warning block found at %@!", self.sourceFileInfo);
- return YES;
- }
- GBLogDebug(@" - Found warning block '%@' at %@.", [string normalizedDescription], self.sourceFileInfo);
-
- // If there isn't paragraph registered yet, create one now, otherwise we'll just add the block to previous paragraph.
- [self pushParagraphIfStackIsEmpty];
-
- // Prepare paragraph item by setting up it's description paragraph, split the string into items and register all items to paragraph. Note that this code effectively ends block paragraph here, so any subsequent block will be added to current paragraph instead. This allows @bug blocks being written anywhere in the documentation, but prevents having more than one paragraph within.
- GBParagraphSpecialItem *item = [GBParagraphSpecialItem specialItemWithType:GBSpecialItemTypeWarning stringValue:string];
- [self pushParagraph:NO];
- [self registerTextItemsFromStringToCurrentParagraph:description];
- [item registerParagraph:[self peekParagraph]];
- [self popParagraph];
-
- // Register block item to current paragraph.
- [[self peekParagraph] registerItem:item];
- return YES;
-}
-
-- (BOOL)registerBugBlockFromLines:(NSArray *)lines {
- // Bug block is a GBParagraphSpecialItem containing one or more GBCommentParagraph items.
- NSString *regex = self.components.bugSectionRegex;
- if (![[lines firstObject] isMatchedByRegex:regex]) return NO;
-
- // Get the description and warn if empty text was found (we still return YES as the block was properly detected as @bug.
- NSString *string = [NSString stringByCombiningLines:lines delimitWith:@"\n"];
- NSString *description = [string stringByMatching:regex capture:1];
- if ([description length] == 0) {
- if (self.settings.warnOnEmptyDescription) GBLogWarn(@"Empty @bug block found at %@!", self.sourceFileInfo);
- return YES;
- }
- GBLogDebug(@" - Found bug block '%@' at %@.", [string normalizedDescription], self.sourceFileInfo);
-
- // If there isn't paragraph registered yet, create one now, otherwise we'll just add the block to previous paragraph.
- [self pushParagraphIfStackIsEmpty];
-
- // Prepare paragraph item by setting up it's description paragraph, split the string into items and register all items to paragraph. Note that this code effectively ends block paragraph here, so any subsequent block will be added to current paragraph instead. This allows @bug blocks being written anywhere in the documentation, but prevents having more than one paragraph within.
- GBParagraphSpecialItem *item = [GBParagraphSpecialItem specialItemWithType:GBSpecialItemTypeBug stringValue:string];
- [self pushParagraph:NO];
- [self registerTextItemsFromStringToCurrentParagraph:description];
- [item registerParagraph:[self peekParagraph]];
- [self popParagraph];
-
- // Register block item to current paragraph.
- [[self peekParagraph] registerItem:item];
- return YES;
-}
-
-- (BOOL)registerExampleBlockFromLines:(NSArray *)lines {
- // Example block is a GBParagraphSpecialItem containing one or more GBCommentParagraph items. The block is only considered as example if each line is prefixed with a single tab or 4 spaces. That leading whitespace is removed from each line in registered data. Note that we allow having mixed lines where one starts with tab and another with spaces!
-
- // Validate all lines match required prefix. Note that we first used dictionaryByMatchingRegex:withKeysAndCaptures: but it ended with EXC_BAD_ACCESS and I couldn't figure it out, so reverted to captureComponentsMatchedByRegex:
- NSString *regex = self.components.exampleSectionRegex;
- NSMutableArray *linesOfCaptures = [NSMutableArray arrayWithCapacity:[lines count]];
- for (NSString *line in lines) {
- NSArray *match = [line captureComponentsMatchedByRegex:regex];
- if ([match count] == 0) return NO;
- [linesOfCaptures addObject:match];
- }
-
- // So all lines are indeed prefixed with required example whitespace, let's create the item. First prepare string value containing only text without prefix. Note that capture index 0 contains full text, index 1 just the prefix and index 2 just the text.
- NSMutableString *stringValue = [NSMutableString string];
- [linesOfCaptures enumerateObjectsUsingBlock:^(NSArray *captures, NSUInteger idx, BOOL *stop) {
- if ([stringValue length] > 0) [stringValue appendString:@"\n"];
- NSString *lineText = [captures objectAtIndex:2];
- [stringValue appendString:lineText];
- }];
- if ([stringValue length] == 0) {
- if (self.settings.warnOnEmptyDescription) GBLogWarn(@"Found empty example block at %@!", self.sourceFileInfo);
- return YES;
- }
- GBLogDebug(@" - Found example block '%@' at %@.", [stringValue normalizedDescription], self.sourceFileInfo);
- NSString *escapedHTML = [self.settings stringByEscapingHTML:stringValue];
-
- // If there isn't paragraph registered yet, create one now, otherwise we'll just add the block to previous paragraph.
- [self pushParagraphIfStackIsEmpty];
-
- // Prepare paragraph item. Note that we don't use paragraphs stack as currently we don't process the text for cross refs!
- GBParagraphSpecialItem *item = [GBParagraphSpecialItem specialItemWithType:GBSpecialItemTypeExample stringValue:stringValue];
- GBCommentParagraph *paragraph = [GBCommentParagraph paragraph];
- [paragraph registerItem:[GBParagraphTextItem paragraphItemWithStringValue:escapedHTML]];
- [item registerParagraph:paragraph];
-
- // Register example block to current paragraph.
- [[self peekParagraph] registerItem:item];
- return YES;
-}
-
-- (BOOL)registerListBlockFromLines:(NSArray *)lines {
- // List block contains a hierarhcy of lists, each represented as a GBParagraphListItem, with it's items as GBCommentParagraph. The method handles both, ordered and unordered lists in any depth and any combination. NOTE: list items can be prefixed by tabs or spaces or combination of both, however it's recommended to use single case as depth is calculated simply by testing prefix string length (so single tab is considered same depth as single space).
-#define isMatchingListItemStatement(theText) \
- ([theText isMatchedByRegex:unorderedRegex] || [theText isMatchedByRegex:orderedRegex])
-
- // If the first line doesn't contain directive, exit.
- // If first line doesn't start a list, we should exit.
- NSString *unorderedRegex = self.components.unorderedListRegex;
- NSString *orderedRegex = self.components.orderedListRegex;
- if (!isMatchingListItemStatement([lines firstObject])) return NO;
- GBLogDebug(@" - Found list block at %@.", self.sourceFileInfo);
-
- // In the first pass, convert the array of lines into an array of pre-processed items. Each item is a dictionary containing the text and line number. The main reason for this step is to combine multiple line item texts into a single string.
- NSMutableArray *items = [NSMutableArray arrayWithCapacity:[lines count]];
- [lines enumerateObjectsUsingBlock:^(NSString *line, NSUInteger idx, BOOL *stop) {
- if (isMatchingListItemStatement(line)) {
- NSMutableDictionary *data = [NSMutableDictionary dictionaryWithCapacity:3];
- [data setObject:line forKey:@"text"];
- [data setObject:[NSNumber numberWithInt:self.currentStartLine + idx] forKey:@"line"];
- [items addObject:data];
- } else {
- NSMutableDictionary *data = [items lastObject];
- NSString *text = [[data objectForKey:@"text"] stringByAppendingFormat:@"\n%@", line];
- [data setObject:text forKey:@"text"];
- }
- }];
-
- // If there isn't paragraph registered yet, create one now, otherwise we'll just add the block to previous paragraph.
- [self pushParagraphIfStackIsEmpty];
- NSUInteger paragraphsStackSize = [self.paragraphsStack count];
-
- // Now process all items and register all data. Note that each list is described by GBParagraphListItem while it's individual items are represented by GBCommentParagraph objects, where each item can additionally contain sublists, again in the form of GBParagraphListItem (this might be confusing due to usage of words "list item" in the class, but the "item" refers to "paragraph item", not to the list). Here's a graph to make it more obvious:
- // - GBParagraphListItem (root list, one object created for each list found)
- // - GBCommentParagraph (item1's description)
- // - GBCommentParagraph (item2's description)
- // - GBParagraphListItem (item2's sublist)
- // - GBCommentParagraph (item2.1's description)
- NSMutableArray *listsStack = [NSMutableArray arrayWithCapacity:[items count]];
- NSMutableArray *indentsStack = [NSMutableArray arrayWithCapacity:[items count]];
- [items enumerateObjectsUsingBlock:^(NSDictionary *itemData, NSUInteger idx, BOOL *stop) {
- BOOL ordered = NO;
- NSArray *components = nil;
- NSString *text = [itemData objectForKey:@"text"];
- NSString *sourceInfo = [NSString stringWithFormat:@"%@%%@", self.currentComment.sourceInfo.filename, [itemData objectForKey:@"line"]];
-
- // Match list item.
- components = [text captureComponentsMatchedByRegex:unorderedRegex];
- if ([components count] > 0) {
- ordered = NO;
- } else {
- components = [text captureComponentsMatchedByRegex:orderedRegex];
- ordered = YES;
- }
-
- // Get item components.
- NSString *indent = [components objectAtIndex:1];
- NSString *stringValue = [components objectAtIndex:2];
-
- if ([listsStack count] == 0 || [indent length] > [[indentsStack peek] length]) {
- // If lists stack is empty, create root list that will hold all items and push original indent. If we found greater indent, we need to start sublist.
- GBLogDebug(@" - Starting list at level %lu...", [indentsStack count] + 1);
- GBParagraphListItem *item = ordered ? [GBParagraphListItem orderedParagraphListItem] : [GBParagraphListItem unorderedParagraphListItem];
- [[self peekParagraph] registerItem:item];
- [listsStack push:item];
- [indentsStack push:indent];
- } else if ([indent length] < [[indentsStack peek] length]) {
- // If indent level is smaller, end sublist and pop current indents until we find a match. Note that we also need to close current paragraph belonging to previous item at the same level!
- while ([indentsStack count] > 0 && [indent length] < [[indentsStack lastObject] length]) {
- GBLogDebug(@" - Ending list at level %lu...", [indentsStack count]);
- [self popParagraph];
- [listsStack pop];
- [indentsStack pop];
- }
- [self popParagraph];
- } else {
- // If indent matches current one, we're adding new item to current list, but we need to close previous item's paragraph!
- [self popParagraph];
- }
-
- // Create GBCommentParagraph representing item's text and process the text. We'll end the paragraph representing item's text and sublists when we find another item at the same level or find items at lower levels...
- GBLogDebug(@" - Creating list item '%@' from %@ at level %lu...", [stringValue normalizedDescription], sourceInfo, [indentsStack count]);
- GBParagraphListItem *list = [listsStack peek];
- [list registerItem:[self pushParagraph:NO]];
- [self registerTextItemsFromStringToCurrentParagraph:stringValue];
- }];
-
- // At the end we need to unwind paragraphs stack until we clear all added paragraphs.
- while ([self.paragraphsStack count] > paragraphsStackSize) [self popParagraph];
- return YES;
-}
-
-- (BOOL)registerDirectivesBlockFromLines:(NSArray *)lines {
- // Registers a block containing directives (@param, @return etc.).
- // If the first line doesn't contain directive, exit.
- NSString *parameterRegex = self.components.parameterDescriptionRegex;
- NSString *exceptionRegex = self.components.exceptionDescriptionRegex;
- NSString *returnRegex = self.components.returnDescriptionRegex;
- NSString *crossRefRegex = self.components.crossReferenceRegex;
- if (![self isLineMatchingDirectiveStatement:[lines firstObject]]) return NO;
-
- // In the first pass, convert the array of lines into an array of pre-processed directive items. Note that we use simplified grouping - if a line matches any directive, we start new directive, otherwise we append text to previous one. The result is an array containing dictionaries with text and line number. Exit if we didn't match any directive.
- NSMutableArray *directives = [NSMutableArray arrayWithCapacity:[lines count]];
- for (NSUInteger i=0; i<[lines count]; i++) {
- NSString *line = [lines objectAtIndex:i];
- if ([self isLineMatchingDirectiveStatement:line]) {
- NSMutableDictionary *data = [NSMutableDictionary dictionaryWithCapacity:2];
- [data setObject:line forKey:@"text"];
- [data setObject:[NSNumber numberWithInt:self.currentStartLine + i] forKey:@"line"];
- [directives addObject:data];
- } else if (i > 0) {
- NSMutableDictionary *data = [directives lastObject];
- NSString *text = [[data objectForKey:@"text"] stringByAppendingFormat:@"\n%@", line];
- [data setObject:text forKey:@"text"];
- } else {
- return NO;
- }
- };
- GBLogDebug(@" - Found directives block at %@.", self.sourceFileInfo);
-
- // Process all directives. Note that we must not immediately close paragraphs as we can find additional paragraph blocks belonging to the paragraph later on (i.e. list blocks, example blocks etc.).
- [directives enumerateObjectsUsingBlock:^(NSDictionary *data, NSUInteger idx, BOOL *stop) {
- NSArray *components = nil;
- NSString *directive = [data objectForKey:@"text"];
- NSString *sourceInfo = [NSString stringWithFormat:@"%@@%@", self.currentComment.sourceInfo.filename, [data objectForKey:@"line"]];
-
- // We must close previous directive description paragraph when we encounter another one. Note that this won't register the paragraph to comment as we opened each by specifying them as non-auto registered paragraphs. We leave last directive description paragraph open - we want to add any following paragraph blocks to. The paragraph will be closed either when we end processing or when we encounter another text block. Also note that we don't pop if stack is empty. This can happen when registering @see items which don't push paragraphs!
- if (idx > 0 && ![self.paragraphsStack isEmpty]) [self popParagraph];
-
- // Match @param.
- components = [directive captureComponentsMatchedByRegex:parameterRegex];
- if ([components count] > 0) {
- NSString *name = [components objectAtIndex:1];
- NSString *text = [components objectAtIndex:2];
- GBLogDebug(@" - Found parameter %@ directive with description '%@' at %@...", name, [text normalizedDescription], sourceInfo);
- GBCommentParagraph *paragraph = [self pushParagraph:NO];
- [self registerTextItemsFromStringToCurrentParagraph:text];
- GBCommentArgument *argument = [GBCommentArgument argumentWithName:name description:paragraph];
- [self.currentComment registerParameter:argument];
- return;
- }
-
- // Match @exception.
- components = [directive captureComponentsMatchedByRegex:exceptionRegex];
- if ([components count] > 0) {
- NSString *name = [components objectAtIndex:1];
- NSString *text = [components objectAtIndex:2];
- GBLogDebug(@" - Found exception %@ directive with description '%@' at %@...", name, [text normalizedDescription], sourceInfo);
- GBCommentParagraph *paragraph = [self pushParagraph:NO];
- [self registerTextItemsFromStringToCurrentParagraph:text];
- GBCommentArgument *argument = [GBCommentArgument argumentWithName:name description:paragraph];
- [self.currentComment registerException:argument];
- return;
- }
-
- // Match @return.
- components = [directive captureComponentsMatchedByRegex:returnRegex];
- if ([components count] > 0) {
- NSString *text = [components objectAtIndex:1];
- GBLogDebug(@" - Matched result directive with description '%@' at %@...", [text normalizedDescription], sourceInfo);
- GBCommentParagraph *paragraph = [self pushParagraph:NO];
- [self registerTextItemsFromStringToCurrentParagraph:text];
- [self.currentComment registerResult:paragraph];
- return;
- }
-
- // Match @see.
- components = [directive captureComponentsMatchedByRegex:crossRefRegex];
- if ([components count] > 0) {
- NSString *text = [components objectAtIndex:1];
- GBParagraphLinkItem *item = [self linkItemFromString:text range:nil description:nil templated:NO];
- if (item) {
- GBLogDebug(@" - Matched cross ref directive %@ at %@...", text, sourceInfo);
- [self.currentComment registerCrossReference:item];
- } else if (self.settings.warnOnInvalidCrossReference && !self.currentComment.isCopied) {
- GBLogWarn(@"Invalid cross ref %@ found at %@!", text, sourceInfo);
- }
- return;
- }
-
- // If the line doesn't contain known directive, warn the user.
- if (self.settings.warnOnUnknownDirective) GBLogWarn(@"Found unknown directive '%@' at %@!", directive, sourceInfo);
- }];
-
- return YES;
-}
-
-- (void)registerTextBlockFromLines:(NSArray *)lines {
- // Registers standard text from the given block of lines. This always starts a new paragraph. Note that this method is just convenience method for registerTextItemsFromStringToCurrentParagraph:. Also note that we keep paragraph open as we may need to append one of the paragraph item blocks later on.
- NSString *stringValue = [NSString stringByCombiningLines:lines delimitWith:@"\n"];
- GBLogDebug(@" - Found text block '%@' at %@.", [stringValue normalizedDescription], self.sourceFileInfo);
- [self pushParagraph:YES];
- [self registerTextItemsFromStringToCurrentParagraph:stringValue];
+// // The given range is guaranteed to point to actual block within the lines array, so we only need to determine the kind of block and how to handle it.
+// NSArray *block = [lines subarrayWithRange:range];
+// self.currentStartLine = self.currentComment.sourceInfo.lineNumber + range.location;
+//
+// // If the block defines one of the known paragraph items, register it and return. Note that paragraph items are simply added to previous paragraph, however if no paragraph exists yet, this will automatically create one.
+// if ([self registerExampleBlockFromLines:block]) return;
+// if ([self registerBugBlockFromLines:block]) return;
+// if ([self registerWarningBlockFromlines:block]) return;
+// if ([self registerListBlockFromLines:block]) return;
+// if ([self registerDirectivesBlockFromLines:block]) return;
+//
+// // If nothing else is matched, the block is standard text. For that we need to start a new paragraph and process the text. Note that we first need to close all open paragraphs - even if the paragraph was started by a known paragraph item block, new text block always starts a new paragraph at this point. But we must keep the new paragraph open in case next block defines an item.
+// [self popAllParagraphs];
+// [self registerTextBlockFromLines:block];
}
- (BOOL)isLineMatchingDirectiveStatement:(NSString *)string {
@@ -453,349 +130,6 @@ - (BOOL)isLineMatchingDirectiveStatement:(NSString *)string {
return NO;
}
-#pragma mark Comment text processing
-
-- (void)registerTextItemsFromStringToCurrentParagraph:(NSString *)string {
- // Registers the text from the given string to last paragraph. Text is converted to an array of GBParagraphTextItem, GBParagraphLinkItem and GBParagraphDecoratorItem objects. This is the main entry point for text processing, this is the only message that should be used for processing text from higher level methods. WARNING: The client is responsible for adding proper paragraph to the stack!
- NSString *simplified = [string stringByReplacingOccurrencesOfRegex:@"(\\*_|_\\*)" withString:@"=!="];
- NSArray *components = [simplified arrayOfDictionariesByMatchingRegex:@"(?s:(\\*|_|=!=|`)(.*?)\\1)" withKeysAndCaptures:@"type", 1, @"value", 2, nil];
- GBCommentParagraph *paragraph = [self peekParagraph];
- NSRange search = NSMakeRange(0, [simplified length]);
- for (NSDictionary *component in components) {
- // Get range of next formatted section. If not found, exit (we'll deal with remaining text after the loop).
- NSString *type = [component objectForKey:@"type"];
- NSRange range = [simplified rangeOfString:type options:0 range:search];
- if (range.location == NSNotFound) break;
-
- // If we skipped some text, add it before handling formatted part!
- if (range.location > search.location) {
- NSRange skippedRange = NSMakeRange(search.location, range.location - search.location);
- NSString *skippedText = [simplified substringWithRange:skippedRange];
- GBLogDebug(@" - Found '%@' text at %@, processing for cross refs...", skippedText, self.sourceFileInfo);
- [self registerTextAndLinkItemsFromString:skippedText toObject:paragraph];
- }
-
- // Get formatted text and prepare properly decorated component. Note that we warn the user if we find unknown decorator type (this probably just means we changed some decorator value by forgot to change this part, so it's some sort of "exception" catching).
- NSString *text = [component valueForKey:@"value"];
- if ([text length] > 0) {
- GBParagraphDecoratorItem *decorator = [GBParagraphDecoratorItem paragraphItemWithStringValue:text];
- if ([type isEqualToString:@"*"]) {
- GBLogDebug(@" - Found '%@' formatted as bold at %@, processing for cross refs...", [text normalizedDescription], self.sourceFileInfo);
- decorator.decorationType = GBDecorationTypeBold;
- } else if ([type isEqualToString:@"_"]) {
- GBLogDebug(@" - Found '%@' formatted as italics at %@, processing for cross refs...", [text normalizedDescription], self.sourceFileInfo);
- decorator.decorationType = GBDecorationTypeItalics;
- } else if ([type isEqualToString:@"`"]) {
- GBLogDebug(@" - Found '%@' formatted as code at %@, processing for cross refs...", [text normalizedDescription], self.sourceFileInfo);
- decorator.decorationType = GBDecorationTypeCode;
- } else if ([type isEqualToString:@"=!="]) {
- // Note that this case requires us to properly registere text to inner decorator but register outer one to the paragraph, so we do it manually!
- GBLogDebug(@" - Found '%@' formatted as bold-italics at %@, processing for cross refs...", [text normalizedDescription], self.sourceFileInfo);
- GBParagraphDecoratorItem *inner = [GBParagraphDecoratorItem paragraphItemWithStringValue:text];
- decorator.decorationType = GBDecorationTypeBold;
- [decorator registerItem:inner];
- inner.decorationType = GBDecorationTypeItalics;
- [self registerTextAndLinkItemsFromString:text toObject:inner];
- [paragraph registerItem:decorator];
- decorator = nil;
- } else {
- if (self.settings.warnOnUnknownDirective) GBLogWarn(@"Unknown text decorator type %@ detected at %@!", type, self.sourceFileInfo);
- decorator = nil;
- }
-
- if (decorator) {
- [self registerTextAndLinkItemsFromString:text toObject:decorator];
- [paragraph registerItem:decorator];
- }
- }
-
- // Prepare next search range.
- NSUInteger location = range.location + range.length * 2 + [text length];
- search = NSMakeRange(location, [simplified length] - location);
- };
-
- // If we have some remaining text, append it now.
- if ([simplified length] > search.location) {
- NSString *remainingText = [simplified substringWithRange:search];
- GBLogDebug(@" - Found '%@' text at %@, processing for cross refs...", [remainingText normalizedDescription], self.sourceFileInfo);
- [self registerTextAndLinkItemsFromString:remainingText toObject:paragraph];
- }
-}
-
-- (void)registerTextAndLinkItemsFromString:(NSString *)string toObject:(id)object {
- // Scans the given string for possible links and converts the text to an array of GBParagraphTextItem and GBParagraphLinkItem objects which are ultimately registered to the given object. NOTE: This message is intended to be sent from registerTextItemsFromStringToCurrentParagraph: and should not be used otherwise! WARNING: The given object must respond to registerItem: message!
-#define registerTextItemFromString(theString) \
- if ([theString length] > 0) { \
- GBLogDebug(@" - Found text '%@'...", [theString normalizedDescription]); \
- GBParagraphTextItem *textItem = [GBParagraphTextItem paragraphItemWithStringValue:theString]; \
- [object registerItem:textItem]; \
- [theString setString:@""]; \
- }
-#define registerLinkItem(theItem, theType) { \
- GBLogDebug(@" - Found %@ %@ cross ref..", theType, theItem.stringValue); \
- [object registerItem:theItem]; \
-}
-#define skipTextFromString(theString) { \
- if (theString) { \
- [text appendString:theString]; \
- string = [string substringFromIndex:[theString length]]; \
- } \
-}
- // Progressively chip away the string and test if it starts with any known cross reference. If so, register link item, otherwise consider the text as normal text item, so skip to the next word.
- NSMutableString *text = [NSMutableString stringWithCapacity:[string length]];
- NSRange range = NSMakeRange(0, 0);
- while ([string length] > 0) {
- // If the string starts with any recognized cross reference, add the link item and skip it's text, otherwise mark the word until next whitespace as text item.
- NSString *description = nil;
- GBParagraphLinkItem *linkItem = [self linkItemFromString:string range:&range description:&description templated:YES];
- if (linkItem) {
- skipTextFromString([string substringToIndex:range.location]);
- registerTextItemFromString(text);
- registerLinkItem(linkItem, description);
- string = [string substringFromIndex:range.length];
- } else {
- skipTextFromString([string stringByMatching:@"^\\S+"]);
- }
-
- // Skip any leading whitespace until the next word and mark it as text item.
- skipTextFromString([string stringByMatching:@"^\\s+"]);
- }
-
- // Append any remaining text
- registerTextItemFromString(text);
-}
-
-#pragma mark Cross references detection
-
-- (id)linkItemFromString:(NSString *)string range:(NSRange *)range description:(NSString **)description templated:(BOOL)templated {
- // Matches any cross reference at the start of the given string and creates GBParagraphLinkItem, match range and description suitable for logging if found. If the string doesn't represent any known cross reference, nil is returned and the other parameters are left untouched. Note that the order of testing is somewhat important (for example we should test for category before class or protocol to avoid text up to open parenthesis being recognized as a class where in fact it's category).
- GBParagraphLinkItem *result = nil;
- NSString *desc = nil;
- if ((result = [self categoryLinkFromString:string range:range templated:templated])) {
- desc = @"category";
- } else if ((result = [self classLinkFromString:string range:range templated:templated])) {
- desc = @"class";
- } else if ((result = [self protocolLinkFromString:string range:range templated:templated])) {
- desc = @"protocol";
- } else if ((result = [self documentLinkFromString:string range:range templated:templated])) {
- desc = @"document";
- } else if ((result = [self remoteMemberLinkItemFromString:string range:range templated:templated])) {
- desc = @"remote member";
- } else if ((result = [self localMemberLinkFromString:string range:range templated:templated])) {
- desc = @"local member";
- } else if ((result = [self urlLinkItemFromString:string range:range templated:templated])) {
- desc = @"url";
- }
- if (result && description) *description = desc;
- return result;
-}
-
-- (id)remoteMemberLinkItemFromString:(NSString *)string range:(NSRange *)range templated:(BOOL)templated {
- // Matches the beginning of the string for remote member cross reference (in the format [Object member]). If found, GBParagraphLinkItem is prepared and returned. NOTE: The range argument is used to return the range of all link text, including optional <> markers.
- // If the string starts with remote link
- NSArray *components = [string captureComponentsMatchedByRegex:[self.components remoteMemberCrossReferenceRegex:templated]];
- if ([components count] == 0) return nil;
-
- // Get link components. Index 0 contains full text, including optional <>, index 1 object name, index 2 member name.
- NSString *linkText = [components objectAtIndex:0];
- NSString *objectName = [components objectAtIndex:1];
- NSString *memberName = [components objectAtIndex:2];
-
- // Validate the link to match it to known object. If no known object is matched, warn, update search range and continue with remaining text. This is required so that we treat unknown objects as normal text later on and still catch proper references that may be hiding in the remainder.
- id referencedObject = [self.store classWithName:objectName];
- if (!referencedObject) {
- referencedObject = [self.store categoryWithName:objectName];
- if (!referencedObject) {
- referencedObject = [self.store protocolWithName:objectName];
- if (!referencedObject) {
- if (self.settings.warnOnInvalidCrossReference) GBLogWarn(@"Invalid %@ reference found near %@, unknown object!", linkText, self.sourceFileInfo);
- return nil;
- }
- }
- }
-
- // Ok, so we have found referenced object in store, now search the member. If member isn't recognized, warn, update search range and continue with remaining text. This is required so that we treat unknown members as normal text later on and still catch proper references in remainder.
- id referencedMember = [[referencedObject methods] methodBySelector:memberName];
- if (!referencedMember) {
- if (self.settings.warnOnInvalidCrossReference) GBLogWarn(@"Invalid %@ reference found near %@, unknown method!", linkText, self.sourceFileInfo);
- return nil;
- }
-
- // Right, we have valid reference to known remote member, create the link item, prepare range and return.
- NSString *stringValue = [linkText stringByTrimmingCharactersInSet:[NSCharacterSet characterSetWithCharactersInString:@"<>"]];
- GBParagraphLinkItem *result = [GBParagraphLinkItem paragraphItemWithStringValue:stringValue];
- result.href = [self.settings htmlReferenceForObject:referencedMember fromSource:self.currentContext];
- result.context = referencedObject;
- result.member = referencedMember;
- result.isLocal = NO;
- if (range) *range = [string rangeOfString:linkText];
- return result;
-}
-
-- (id)localMemberLinkFromString:(NSString *)string range:(NSRange *)range templated:(BOOL)templated {
- // Matches the beginning of the string for local member cross reference. If found, GBParagraphLinkItem is prepared and returned. NOTE: The range argument is used to return the range of all link text, including optional <> markers. NOTE: Note that we can skip local member cross ref testing if no context (i.e. class, category or protocol) is given!
- if (!self.currentContext) return nil;
- NSArray *components = [string captureComponentsMatchedByRegex:[self.components localMemberCrossReferenceRegex:templated]];
- if ([components count] == 0) return nil;
-
- // Get link components. Index 0 contains full text, including optional <>, index 1 just the member selector.
- NSString *linkText = [components objectAtIndex:0];
- NSString *selector = [components objectAtIndex:1];
-
- // Validate the selector against the context. If context doesn't implement the method, exit.
- GBMethodData *referencedMethod = [[[self currentContext] methods] methodBySelector:selector];
- if (!referencedMethod) return nil;
-
- // Ok, we have valid method, return the link item.
- GBParagraphLinkItem *result = [GBParagraphLinkItem paragraphItemWithStringValue:selector];
- result.href = [self.settings htmlReferenceForObject:referencedMethod fromSource:self.currentContext];
- result.context = self.currentContext;
- result.member = referencedMethod;
- result.isLocal = YES;
- if (range) *range = [string rangeOfString:linkText];
- return result;
-}
-
-- (id)classLinkFromString:(NSString *)string range:(NSRange *)range templated:(BOOL)templated {
- // Matches the beginning of the string for class cross reference. If found, GBParagraphLinkItem is prepared and returned. NOTE: The range argument is used to return the range of all link text, including optional <> markers.
- NSArray *components = [string captureComponentsMatchedByRegex:[self.components objectCrossReferenceRegex:templated]];
- if ([components count] == 0) return nil;
-
- // Get link components. Index 0 contains full text, including optional <>, index 1 just the object name.
- NSString *linkText = [components objectAtIndex:0];
- NSString *objectName = [components objectAtIndex:1];
-
- // Validate the selector against the context. If context doesn't implement the method, exit.
- GBClassData *referencedObject = [self.store classWithName:objectName];
- if (!referencedObject) return nil;
-
- // Ok, we have valid method, return the link item.
- GBParagraphLinkItem *result = [GBParagraphLinkItem paragraphItemWithStringValue:objectName];
- result.href = [self.settings htmlReferenceForObject:referencedObject fromSource:self.currentContext];
- result.context = referencedObject;
- result.isLocal = (referencedObject == self.currentContext);
- if (range) *range = [string rangeOfString:linkText];
- return result;
-}
-
-- (id)categoryLinkFromString:(NSString *)string range:(NSRange *)range templated:(BOOL)templated {
- // Matches the beginning of the string for category cross reference. If found, GBParagraphLinkItem is prepared and returned. NOTE: The range argument is used to return the range of all link text, including optional <> markers.
- NSArray *components = [string captureComponentsMatchedByRegex:[self.components categoryCrossReferenceRegex:templated]];
- if ([components count] == 0) return nil;
-
- // Get link components. Index 0 contains full text, including optional <>, index 1 just the object name.
- NSString *linkText = [components objectAtIndex:0];
- NSString *objectName = [components objectAtIndex:1];
-
- // Validate the selector against the context. If context doesn't implement the method, exit.
- GBCategoryData *referencedObject = [self.store categoryWithName:objectName];
- if (!referencedObject) return nil;
-
- // Ok, we have valid method, return the link item.
- GBParagraphLinkItem *result = [GBParagraphLinkItem paragraphItemWithStringValue:objectName];
- result.href = [self.settings htmlReferenceForObject:referencedObject fromSource:self.currentContext];
- result.context = referencedObject;
- result.isLocal = (referencedObject == self.currentContext);
- if (range) *range = [string rangeOfString:linkText];
- return result;
-}
-
-- (id)protocolLinkFromString:(NSString *)string range:(NSRange *)range templated:(BOOL)templated {
- // Matches the beginning of the string for protocol cross reference. If found, GBParagraphLinkItem is prepared and returned. NOTE: The range argument is used to return the range of all link text, including optional <> markers.
- NSArray *components = [string captureComponentsMatchedByRegex:[self.components objectCrossReferenceRegex:templated]];
- if ([components count] == 0) return nil;
-
- // Get link components. Index 0 contains full text, including optional <>, index 1 just the object name.
- NSString *linkText = [components objectAtIndex:0];
- NSString *objectName = [components objectAtIndex:1];
-
- // Validate the selector against the context. If context doesn't implement the method, exit.
- GBProtocolData *referencedObject = [self.store protocolWithName:objectName];
- if (!referencedObject) return nil;
-
- // Ok, we have valid method, return the link item.
- GBParagraphLinkItem *result = [GBParagraphLinkItem paragraphItemWithStringValue:objectName];
- result.href = [self.settings htmlReferenceForObject:referencedObject fromSource:self.currentContext];
- result.context = referencedObject;
- result.isLocal = (referencedObject == self.currentContext);
- if (range) *range = [string rangeOfString:linkText];
- return result;
-}
-
-- (id)documentLinkFromString:(NSString *)string range:(NSRange *)range templated:(BOOL)templated {
- // Matches the beginning of the string for document cross reference. If found, GBParagraphLinkItem is prepared and returned. NOTE: The range argument is used to return the range of all link text, including optional <> markers.
- NSArray *components = [string captureComponentsMatchedByRegex:[self.components documentCrossReferenceRegex:templated]];
- if ([components count] == 0) return nil;
-
- // Get link components. Index 0 contains full text, including optional <>, index 1 just the object name.
- NSString *linkText = [components objectAtIndex:0];
- NSString *objectName = [components objectAtIndex:1];
-
- // Get the document from the store - note that we need to add -template extension! If not found, exit.
- NSString *objectID = [self.settings templateFilenameForOutputPath:objectName];
- GBDocumentData *referencedObject = [self.store documentWithName:objectID];
- if (!referencedObject) return nil;
-
- // Ok, we have valid method, return the link item.
- GBParagraphLinkItem *result = [GBParagraphLinkItem paragraphItemWithStringValue:objectName];
- result.href = [self.settings htmlReferenceForObject:referencedObject fromSource:self.currentContext];
- result.context = referencedObject;
- result.isLocal = (referencedObject == self.currentContext);
- if (range) *range = [string rangeOfString:linkText];
- return result;
-}
-
-- (id)urlLinkItemFromString:(NSString *)string range:(NSRange *)range templated:(BOOL)templated {
- // Matches the beginning of the string for URL cross reference. If found, GBParagraphLinkItem is prepared and returned. NOTE: The range argument is used to return the range of all link text, including optional <> markers.
- NSArray *components = [string captureComponentsMatchedByRegex:[self.components urlCrossReferenceRegex:templated]];
- if ([components count] == 0) return nil;
-
- // Get link components. Index 0 contains full text, including optional <>, index 1 just the URL address.
- NSString *linkText = [components objectAtIndex:0];
- NSString *address = [components objectAtIndex:1];
-
- // Create link item, prepare range and return.
- GBParagraphLinkItem *result = [GBParagraphLinkItem paragraphItemWithStringValue:address];
- result.href = address;
- if (range) *range = [string rangeOfString:linkText];
- return result;
-}
-
-#pragma mark Helper methods
-
-- (GBCommentParagraph *)pushParagraphIfStackIsEmpty {