Permalink
Browse files

Implemented optional disabling of first paragraph repeat for members.…

… Closes #29.

By default appledoc repeats first paragraph in members documentation. This can be optionally disabled with command line switch now.
  • Loading branch information...
1 parent 6d71e96 commit efce66926a9195ae0eeafee10caeee00c7b8c436 @tomaz committed Jan 3, 2011
@@ -31,6 +31,7 @@
static NSString *kGBArgCreateDocSet = @"create-docset";
static NSString *kGBArgInstallDocSet = @"install-docset";
static NSString *kGBArgKeepIntermediateFiles = @"keep-intermediate-files";
+static NSString *kGBArgRepeatFirstParagraph = @"repeat-first-par";
static NSString *kGBArgKeepUndocumentedObjects = @"keep-undocumented-objects";
static NSString *kGBArgKeepUndocumentedMembers = @"keep-undocumented-members";
static NSString *kGBArgFindUndocumentedMembersDocumentation = @"search-undocumented-doc";
@@ -212,13 +213,15 @@ - (void)application:(DDCliApplication *)app willParseOptions:(DDGetoptLongParser
{ kGBArgKeepUndocumentedObjects, 0, DDGetoptNoArgument },
{ kGBArgKeepUndocumentedMembers, 0, DDGetoptNoArgument },
{ kGBArgFindUndocumentedMembersDocumentation, 0, DDGetoptNoArgument },
+ { kGBArgRepeatFirstParagraph, 0, DDGetoptNoArgument },
{ kGBArgMergeCategoriesToClasses, 0, DDGetoptNoArgument },
{ kGBArgKeepMergedCategoriesSections, 0, DDGetoptNoArgument },
{ kGBArgPrefixMergedCategoriesSectionsWithCategoryName, 0, DDGetoptNoArgument },
{ GBNoArg(kGBArgKeepIntermediateFiles), 0, DDGetoptNoArgument },
{ GBNoArg(kGBArgKeepUndocumentedObjects), 0, DDGetoptNoArgument },
{ GBNoArg(kGBArgKeepUndocumentedMembers), 0, DDGetoptNoArgument },
{ GBNoArg(kGBArgFindUndocumentedMembersDocumentation), 0, DDGetoptNoArgument },
+ { GBNoArg(kGBArgRepeatFirstParagraph), 0, DDGetoptNoArgument },
{ GBNoArg(kGBArgMergeCategoriesToClasses), 0, DDGetoptNoArgument },
{ GBNoArg(kGBArgKeepMergedCategoriesSections), 0, DDGetoptNoArgument },
{ GBNoArg(kGBArgPrefixMergedCategoriesSectionsWithCategoryName), 0, DDGetoptNoArgument },
@@ -424,13 +427,15 @@ - (void)setKeepIntermediateFiles:(BOOL)value { self.settings.keepIntermediateFil
- (void)setKeepUndocumentedObjects:(BOOL)value { self.settings.keepUndocumentedObjects = value; }
- (void)setKeepUndocumentedMembers:(BOOL)value { self.settings.keepUndocumentedMembers = value; }
- (void)setSearchUndocumentedDoc:(BOOL)value { self.settings.findUndocumentedMembersDocumentation = value; }
+- (void)setRepeatFirstPar:(BOOL)value { self.settings.repeatFirstParagraphForMemberDescription = value; }
- (void)setMergeCategories:(BOOL)value { self.settings.mergeCategoriesToClasses = value; }
- (void)setKeepMergedSections:(BOOL)value { self.settings.keepMergedCategoriesSections = value; }
- (void)setPrefixMergedSections:(BOOL)value { self.settings.prefixMergedCategoriesSectionsWithCategoryName = value; }
- (void)setNoKeepIntermediateFiles:(BOOL)value { self.settings.keepIntermediateFiles = !value;}
- (void)setNoKeepUndocumentedObjects:(BOOL)value { self.settings.keepUndocumentedObjects = !value; }
- (void)setNoKeepUndocumentedMembers:(BOOL)value { self.settings.keepUndocumentedMembers = !value; }
- (void)setNoSearchUndocumentedDoc:(BOOL)value { self.settings.findUndocumentedMembersDocumentation = !value; }
+- (void)setNoRepeatFirstPar:(BOOL)value { self.settings.repeatFirstParagraphForMemberDescription = !value; }
- (void)setNoMergeCategories:(BOOL)value { self.settings.mergeCategoriesToClasses = !value; }
- (void)setNoKeepMergedSections:(BOOL)value { self.settings.keepMergedCategoriesSections = !value; }
- (void)setNoPrefixMergedSections:(BOOL)value { self.settings.prefixMergedCategoriesSectionsWithCategoryName = !value; }
@@ -522,6 +527,7 @@ - (void)printSettingsAndArguments:(NSArray *)arguments {
ddprintf(@"--%@ = %@\n", kGBArgKeepUndocumentedObjects, PRINT_BOOL(self.settings.keepUndocumentedObjects));
ddprintf(@"--%@ = %@\n", kGBArgKeepUndocumentedMembers, PRINT_BOOL(self.settings.keepUndocumentedMembers));
ddprintf(@"--%@ = %@\n", kGBArgFindUndocumentedMembersDocumentation, PRINT_BOOL(self.settings.findUndocumentedMembersDocumentation));
+ ddprintf(@"--%@ = %@\n", kGBArgRepeatFirstParagraph, PRINT_BOOL(self.settings.repeatFirstParagraphForMemberDescription));
ddprintf(@"--%@ = %@\n", kGBArgMergeCategoriesToClasses, PRINT_BOOL(self.settings.mergeCategoriesToClasses));
ddprintf(@"--%@ = %@\n", kGBArgKeepMergedCategoriesSections, PRINT_BOOL(self.settings.keepMergedCategoriesSections));
ddprintf(@"--%@ = %@\n", kGBArgPrefixMergedCategoriesSectionsWithCategoryName, PRINT_BOOL(self.settings.prefixMergedCategoriesSectionsWithCategoryName));
@@ -572,6 +578,7 @@ - (void)printHelp {
PRINT_USAGE(@" ", kGBArgKeepUndocumentedObjects, @"", @"[b] Keep undocumented objects");
PRINT_USAGE(@" ", kGBArgKeepUndocumentedMembers, @"", @"[b] Keep undocumented members");
PRINT_USAGE(@" ", kGBArgFindUndocumentedMembersDocumentation, @"", @"[b] Search undocumented members documentation");
+ PRINT_USAGE(@" ", kGBArgRepeatFirstParagraph, @"", @"[b] Repeat first paragraph in member documentation");
PRINT_USAGE(@" ", kGBArgMergeCategoriesToClasses, @"", @"[b] Merge categories to classes");
PRINT_USAGE(@" ", kGBArgKeepMergedCategoriesSections, @"", @"[b] Keep merged categories sections");
PRINT_USAGE(@" ", kGBArgPrefixMergedCategoriesSectionsWithCategoryName, @"", @"[b] Prefix merged sections with category name");
@@ -110,6 +110,12 @@
/// @name Behavior handling
///---------------------------------------------------------------------------------------
+/** Indicates whether the first paragraph needs to be repeated within method and property description or not.
+
+ If `YES`, first paragraph is repeated in members description, otherwise not.
+ */
+@property (assign) BOOL repeatFirstParagraphForMemberDescription;
+
/* Indicates whether undocumented classes, categories or protocols should be kept or ignored when generating output.
If `YES` undocumented objects are kept and are used for output generation. If `NO`, these objects are ignored, but only if all their members are also not documented - as soon as a single member is documented, the object is included in output together with all of it's documented members.
@@ -54,6 +54,7 @@ - (id)init {
self.createHTML = YES;
self.createDocSet = YES;
self.installDocSet = NO;
+ self.repeatFirstParagraphForMemberDescription = YES;
self.keepIntermediateFiles = NO;
self.keepUndocumentedObjects = NO;
self.keepUndocumentedMembers = NO;
@@ -293,6 +294,7 @@ - (NSString *)description {
@synthesize docsetPublisherName;
@synthesize docsetCopyrightMessage;
+@synthesize repeatFirstParagraphForMemberDescription;
@synthesize keepUndocumentedObjects;
@synthesize keepUndocumentedMembers;
@synthesize findUndocumentedMembersDocumentation;
View
@@ -32,6 +32,7 @@
@interface GBComment : NSObject {
@private
NSMutableArray *_paragraphs;
+ NSMutableArray *_descriptionParagraphs;
NSMutableArray *_parameters;
NSMutableArray *_exceptions;
NSMutableArray *_crossrefs;
@@ -83,6 +84,7 @@
@see registerParagraph:
@see paragraphs
+ @see descriptionParagraphs
*/
@property (retain) GBCommentParagraph *firstParagraph;
@@ -91,6 +93,7 @@
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 descriptionParagraphs
@see registerParagraph:
@see parameters
@see exceptions
@@ -99,6 +102,31 @@
@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.
+
+ 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
///---------------------------------------------------------------------------------------
@@ -218,21 +246,21 @@
/** Indicates whether the comment has at least one paragraph or not.
- This is used mainly to simplify template output generators. Programmatically this method is equal to testing whether `paragraph` count is greater than 0, like this: `[object.paragraphs count] > 0`.
+ 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 hasMultipleParagraphs
+ @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 `paragraph` count is greater than 1, like this: `[object.paragraphs count] > 1`.
+ 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 hasMultipleParagraphs;
+@property (readonly) BOOL hasDescriptionParagraphs;
/** Indicates whether the comment has at least one parameter or not.
View
@@ -40,14 +40,23 @@ + (id)commentWithStringValue:(NSString *)value sourceInfo:(GBSourceInfo *)info {
- (void)registerParagraph:(GBCommentParagraph *)paragraph {
NSParameterAssert(paragraph != nil);
- GBLogDebug(@"Registering %@...", paragraph);
+ 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);
@@ -129,8 +138,8 @@ - (BOOL)hasParagraphs {
return ([self.paragraphs count] > 0);
}
-- (BOOL)hasMultipleParagraphs {
- return ([self.paragraphs count] > 1);
+- (BOOL)hasDescriptionParagraphs {
+ return ([self.descriptionParagraphs count] > 0);
}
- (BOOL)hasParameters {
@@ -207,6 +216,7 @@ - (NSString *)debugDescription {
#pragma mark Properties
+@synthesize descriptionParagraphs = _descriptionParagraphs;
@synthesize paragraphs = _paragraphs;
@synthesize parameters = _parameters;
@synthesize exceptions = _exceptions;
@@ -144,7 +144,17 @@ - (void)processCommentForObject:(GBModelBase *)object {
object.comment = nil;
return;
}
+
+ // Let comments processor parse comment string value into object representation.
[self.commentsProcessor processComment:object.comment withContext:self.currentContext store:self.store];
+
+ // Prepare description paragraphs from registered paragraphs according to application settings.
+ if (!object.comment.hasParagraphs) return;
+ NSArray *paragraphs = object.comment.paragraphs;
+ NSUInteger startIndex = object.isTopLevelObject || (self.settings.repeatFirstParagraphForMemberDescription && [paragraphs count] > 1) ? 0 : 1;
+ for (NSUInteger i=startIndex; i<[paragraphs count]; i++) {
+ [object.comment registerDescriptionParagraph:[paragraphs objectAtIndex:i]];
+ }
}
- (void)processParametersFromComment:(GBComment *)comment matchingMethod:(GBMethodData *)method {
@@ -121,14 +121,14 @@ <h4 class="method-subtitle parameter-title">{{strings/objectMethods/resultTitle}
</div>
{{/result}}
- {{#hasMultipleParagraphs}}
+ {{#hasDescriptionParagraphs}}
<div class="method-subsection discussion-section">
<h4 class="method-subtitle">{{strings/objectMethods/discussionTitle}}</h4>
- {{#paragraphs}}
+ {{#descriptionParagraphs}}
<p>{{>GBCommentParagraph}}</p>
- {{/paragraphs}}
+ {{/descriptionParagraphs}}
</div>
- {{/hasMultipleParagraphs}}
+ {{/hasDescriptionParagraphs}}
{{#hasExceptions}}
<div class="method-subsection arguments-section exceptions">
@@ -163,6 +163,15 @@ - (void)testFindUndocumentedMembersDocumentation_shouldAssignValueToSettings {
assertThatBool(settings2.findUndocumentedMembersDocumentation, equalToBool(NO));
}
+- (void)testRepeatFirstParagraph_shouldAssignValueToSettings {
+ // setup & execute
+ GBApplicationSettingsProvider *settings1 = [self settingsByRunningWithArgs:@"--repeat-first-par", nil];
+ GBApplicationSettingsProvider *settings2 = [self settingsByRunningWithArgs:@"--no-repeat-first-par", nil];
+ // verify
+ assertThatBool(settings1.repeatFirstParagraphForMemberDescription, equalToBool(YES));
+ assertThatBool(settings2.repeatFirstParagraphForMemberDescription, equalToBool(NO));
+}
+
- (void)testMergeCategoriesToClasses_shouldAssignValueToSettings {
// setup & execute
GBApplicationSettingsProvider *settings1 = [self settingsByRunningWithArgs:@"--merge-categories", nil];
@@ -72,15 +72,40 @@ - (void)testHasParagraphs_shouldReturnProperValue {
assertThatBool(comment.hasParagraphs, equalToBool(YES));
}
-- (void)testHasMultipleParagraphs_shouldReturnProperValue {
+#pragma mark Description paragraphs handling
+
+- (void)testRegisterDescriptionParagraph_shouldAddParagraphToList {
+ // setup
+ GBComment *comment = [GBComment commentWithStringValue:@""];
+ GBCommentParagraph *paragraph = [GBCommentParagraph paragraph];
+ // execute
+ [comment registerDescriptionParagraph:paragraph];
+ // verify
+ assertThatInteger([comment.descriptionParagraphs count], equalToInteger(1));
+ assertThat([comment.descriptionParagraphs objectAtIndex:0], is(paragraph));
+}
+
+- (void)testRegisterDescriptionParagraph_shouldAddAllParagraphsToListInOrderRegistered {
+ // setup
+ GBComment *comment = [GBComment commentWithStringValue:@""];
+ GBCommentParagraph *paragraph1 = [GBCommentParagraph paragraph];
+ GBCommentParagraph *paragraph2 = [GBCommentParagraph paragraph];
+ // execute
+ [comment registerDescriptionParagraph:paragraph1];
+ [comment registerDescriptionParagraph:paragraph2];
+ // verify
+ assertThatInteger([comment.descriptionParagraphs count], equalToInteger(2));
+ assertThat([comment.descriptionParagraphs objectAtIndex:0], is(paragraph1));
+ assertThat([comment.descriptionParagraphs objectAtIndex:1], is(paragraph2));
+}
+
+- (void)testHasDescriptionParagraphs_shouldReturnProperValue {
// setup
GBComment *comment = [GBComment commentWithStringValue:@""];
// execute & verify
- assertThatBool(comment.hasMultipleParagraphs, equalToBool(NO));
- [comment registerParagraph:[GBCommentParagraph paragraph]];
- assertThatBool(comment.hasMultipleParagraphs, equalToBool(NO));
- [comment registerParagraph:[GBCommentParagraph paragraph]];
- assertThatBool(comment.hasMultipleParagraphs, equalToBool(YES));
+ assertThatBool(comment.hasDescriptionParagraphs, equalToBool(NO));
+ [comment registerDescriptionParagraph:[GBCommentParagraph paragraph]];
+ assertThatBool(comment.hasDescriptionParagraphs, equalToBool(YES));
}
#pragma mark Parameters testing
Oops, something went wrong.

0 comments on commit efce669

Please sign in to comment.