Permalink
Browse files

Add support for @note tags.

Add support for printing titles of information blocks.

Apple displays "Note:" in bold at the start of their note documentation. We'd like to do the same for warnings and bugs. This is now the default, and can be turned turned on/off with the 'print-information-block-titles' setting.
  • Loading branch information...
1 parent 3de683a commit bc892fce1451af83e88953a82afa4017563ef556 @jerryhjones jerryhjones committed Mar 2, 2012
@@ -41,6 +41,7 @@
static NSString *kGBArgRepeatFirstParagraph = @"repeat-first-par";
static NSString *kGBArgPreprocessHeaderDoc = @"preprocess-headerdoc";
+static NSString *kGBArgPrintInformationBlockTitles = @"print-information-block-titles";
static NSString *kGBArgUseSingleStar = @"use-single-star";
static NSString *kGBArgKeepUndocumentedObjects = @"keep-undocumented-objects";
static NSString *kGBArgKeepUndocumentedMembers = @"keep-undocumented-members";
@@ -274,6 +275,8 @@ - (void)application:(DDCliApplication *)app willParseOptions:(DDGetoptLongParser
{ kGBArgFindUndocumentedMembersDocumentation, 0, DDGetoptNoArgument },
{ kGBArgRepeatFirstParagraph, 0, DDGetoptNoArgument },
{ kGBArgPreprocessHeaderDoc, 0, DDGetoptNoArgument },
+ { kGBArgPrintInformationBlockTitles, 0, DDGetoptNoArgument },
+ { GBNoArg(kGBArgPrintInformationBlockTitles), 0, DDGetoptNoArgument },
{ kGBArgUseSingleStar, 0, DDGetoptNoArgument },
{ kGBArgMergeCategoriesToClasses, 0, DDGetoptNoArgument },
{ kGBArgKeepMergedCategoriesSections, 0, DDGetoptNoArgument },
@@ -675,6 +678,7 @@ - (void)setKeepUndocumentedMembers:(BOOL)value { self.settings.keepUndocumentedM
- (void)setSearchUndocumentedDoc:(BOOL)value { self.settings.findUndocumentedMembersDocumentation = value; }
- (void)setRepeatFirstPar:(BOOL)value { self.settings.repeatFirstParagraphForMemberDescription = value; }
- (void)setPreprocessHeaderdoc:(BOOL)value { self.settings.preprocessHeaderDoc = value; }
+- (void)setPrintInformationBlockTitles:(BOOL)value { self.settings.printInformationBlockTitles = value; }
- (void)setUseSingleStar:(BOOL)value { self.settings.useSingleStarForBold = value; }
- (void)setMergeCategories:(BOOL)value { self.settings.mergeCategoriesToClasses = value; }
- (void)setMergeCategoryComment:(BOOL)value { self.settings.mergeCategoryCommentToClass = value; }
@@ -687,6 +691,7 @@ - (void)setNoSearchUndocumentedDoc:(BOOL)value { self.settings.findUndocumentedM
- (void)setNoRepeatFirstPar:(BOOL)value { self.settings.repeatFirstParagraphForMemberDescription = !value; }
- (void)setNoUseSingleStar:(BOOL)value { self.settings.useSingleStarForBold = !value; }
- (void)setNoPreprocessHeaderdoc:(BOOL)value { self.settings.preprocessHeaderDoc = !value; }
+- (void)setNoPrintInformationBlockTitles:(BOOL)value { self.settings.printInformationBlockTitles = !value; }
- (void)setNoMergeCategories:(BOOL)value { self.settings.mergeCategoriesToClasses = !value; }
- (void)setNoMergeCategoryComment:(BOOL)value { self.settings.mergeCategoryCommentToClass = !value; }
- (void)setNoKeepMergedSections:(BOOL)value { self.settings.keepMergedCategoriesSections = !value; }
@@ -801,6 +806,7 @@ - (void)printSettingsAndArguments:(NSArray *)arguments {
ddprintf(@"--%@ = %@\n", kGBArgFindUndocumentedMembersDocumentation, PRINT_BOOL(self.settings.findUndocumentedMembersDocumentation));
ddprintf(@"--%@ = %@\n", kGBArgRepeatFirstParagraph, PRINT_BOOL(self.settings.repeatFirstParagraphForMemberDescription));
ddprintf(@"--%@ = %@\n", kGBArgPreprocessHeaderDoc, PRINT_BOOL(self.settings.preprocessHeaderDoc));
+ ddprintf(@"--%@ = %@\n", kGBArgPrintInformationBlockTitles, PRINT_BOOL(self.settings.printInformationBlockTitles));
ddprintf(@"--%@ = %@\n", kGBArgUseSingleStar, PRINT_BOOL(self.settings.useSingleStarForBold));
ddprintf(@"--%@ = %@\n", kGBArgMergeCategoriesToClasses, PRINT_BOOL(self.settings.mergeCategoriesToClasses));
ddprintf(@"--%@ = %@\n", kGBArgMergeCategoryComment, PRINT_BOOL(self.settings.mergeCategoryCommentToClass));
@@ -867,6 +873,7 @@ - (void)printHelp {
PRINT_USAGE(@" ", kGBArgFindUndocumentedMembersDocumentation, @"", @"[b] Search undocumented members documentation");
PRINT_USAGE(@" ", kGBArgRepeatFirstParagraph, @"", @"[b] Repeat first paragraph in member documentation");
PRINT_USAGE(@" ", kGBArgPreprocessHeaderDoc, @"", @"[b] Preprocess header doc comments - 10.7 only!");
+ PRINT_USAGE(@" ", kGBArgPrintInformationBlockTitles, @"", @"[b] Print title of information blocks. \"Note:\", \"Warning:\", etc.");
PRINT_USAGE(@" ", kGBArgUseSingleStar, @"", @"[b] Use single star for bold marker");
PRINT_USAGE(@" ", kGBArgMergeCategoriesToClasses, @"", @"[b] Merge categories to classes");
PRINT_USAGE(@" ", kGBArgMergeCategoryComment, @"", @"[b] Merge category comment to class");
@@ -238,6 +238,12 @@ extern id kGBCustomDocumentIndexDescKey;
*/
@property (assign) BOOL preprocessHeaderDoc;
+/** Indicates whether we should prepend the name of an information block before the comment
+
+ If `YES`, appledoc will add "Warning: " to the text of a warning informationg block, "Note: " to note blocks, and "Bug: " to bug blocks.
+ */
+@property (assign) BOOL printInformationBlockTitles;
+
/** Indicates whether we should treat single stars as bold markers or not.
If `YES`, single star markers (`*text*`) should be treated as bold markers (`**text**`), otherwise not. This is mainly used for backwards compatibility, but should be disabled as it can cause unexpected issues, such as converting unordered lists into bold etc.
@@ -85,6 +85,7 @@ - (id)init {
self.publishDocSet = NO;
self.repeatFirstParagraphForMemberDescription = YES;
self.preprocessHeaderDoc = NO;
+ self.printInformationBlockTitles = YES;
self.useSingleStarForBold = NO;
self.keepIntermediateFiles = NO;
self.cleanupOutputPathBeforeRunning = NO;
@@ -601,6 +602,7 @@ - (NSString *)versionIdentifier {
@synthesize repeatFirstParagraphForMemberDescription;
@synthesize preprocessHeaderDoc;
+@synthesize printInformationBlockTitles;
@synthesize useSingleStarForBold;
@synthesize keepUndocumentedObjects;
@synthesize keepUndocumentedMembers;
@@ -51,6 +51,10 @@
/** Returns the regex used for matching bug section with capture 1 containing directive and capture 2 description text. */
@property (readonly) NSString *bugSectionRegex;
+/** Returns the regex used for matching note section with capture 1 containing directive and capture 2 description text. */
+@property (readonly) NSString *noteSectionRegex;
+
+
///---------------------------------------------------------------------------------------
/// @name Method specific definitions
///---------------------------------------------------------------------------------------
@@ -44,6 +44,10 @@ - (id)init {
#pragma mark Sections detection
+- (NSString *)noteSectionRegex {
+ GBRETURN_ON_DEMAND([self descriptionCaptureRegexForKeyword:@"note"]);
+}
+
- (NSString *)warningSectionRegex {
GBRETURN_ON_DEMAND([self descriptionCaptureRegexForKeyword:@"warning"]);
}
@@ -200,6 +200,7 @@ - (void)processCommentBlockInLines:(NSArray *)lines blockRange:(NSRange)blockRan
NSArray *block = [lines subarrayWithRange:blockRange];
if ([self isLineMatchingDirectiveStatement:[block firstObject]]) {
NSString *string = [self stringByCombiningTrimmedLines:block];
+ if ([self processNoteBlockInString:string lines:lines blockRange:blockRange shortRange:shortRange]) return;
if ([self processWarningBlockInString:string lines:lines blockRange:blockRange shortRange:shortRange]) return;
if ([self processBugBlockInString:string lines:lines blockRange:blockRange shortRange:shortRange]) return;
if ([self processParamBlockInString:string lines:lines blockRange:blockRange shortRange:shortRange]) return;
@@ -271,6 +272,24 @@ - (void)registerReservedShortDescriptionIfNecessary {
#pragma mark Directives matching
+- (BOOL)processNoteBlockInString:(NSString *)string lines:(NSArray *)lines blockRange:(NSRange)blockRange shortRange:(NSRange)shortRange {
+ NSArray *components = [string captureComponentsMatchedByRegex:self.components.noteSectionRegex];
+ if ([components count] == 0) return NO;
+
+ // Get data from captures. Index 1 is directive, index 2 description text.
+ NSString *directive = [components objectAtIndex:1];
+ NSString *description = [components objectAtIndex:2];
+ GBLogDebug(@"- Registering note block %@ at %@...", [description normalizedDescription], self.currentSourceInfo);
+ [self registerShortDescriptionFromLines:lines range:shortRange removePrefix:directive];
+
+ // Convert to markdown and register everything. We always use the whole text for directive.
+ GBCommentComponent *component = [self commentComponentByPreprocessingString:description withFlags:0];
+ component.stringValue = string;
+ component.markdownValue = [self stringByConvertingLinesToBlockquoteFromString:component.markdownValue class:@"note"];
+ [self.currentComment.longDescription registerComponent:component];
+ return YES;
+}
+
- (BOOL)processWarningBlockInString:(NSString *)string lines:(NSArray *)lines blockRange:(NSRange)blockRange shortRange:(NSRange)shortRange {
NSArray *components = [string captureComponentsMatchedByRegex:self.components.warningSectionRegex];
if ([components count] == 0) return NO;
@@ -438,6 +457,7 @@ - (BOOL)processRelatedBlockInString:(NSString *)string lines:(NSArray *)lines bl
}
- (BOOL)isLineMatchingDirectiveStatement:(NSString *)string {
+ if ([string isMatchedByRegex:self.components.noteSectionRegex]) return YES;
if ([string isMatchedByRegex:self.components.warningSectionRegex]) return YES;
if ([string isMatchedByRegex:self.components.bugSectionRegex]) return YES;
if ([string isMatchedByRegex:self.components.parameterDescriptionRegex]) return YES;
@@ -717,7 +737,11 @@ - (NSString *)stringByConvertingLinesToBlockquoteFromString:(NSString *)string c
if ([className length] > 0) [result appendFormat:@"> %%%@%%\n", className];
NSArray *lines = [string arrayOfLines];
[lines enumerateObjectsUsingBlock:^(NSString *line, NSUInteger idx, BOOL *stop) {
- [result appendFormat:@"> %@", line];
+ NSString *class = @"";
+ if (self.settings.printInformationBlockTitles && 0 == idx && [className length] > 0) {
+ class = [NSString stringWithFormat:@"**%@:** ", [className capitalizedString]];
+ }
+ [result appendFormat:@"> %@%@", class, line];
if (idx < [lines count] - 1) [result appendString:@"\n"];
}];
return result;
@@ -409,6 +409,13 @@ li#jumpto_button select {
height: 0.7em;
}
+.note {
+ border: 1px solid #5088C5;
+ background-color: white;
+ margin: 1.667em 0 1.75em 0;
+ padding: 0 .667em .083em .750em;
+}
+
.warning {
border: 1px solid #5088C5;
background-color: #F0F3F7;

0 comments on commit bc892fc

Please sign in to comment.