Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Fixed usage of single star as bold marker (kind of). Closes #154.

The problem with star delimited unordered lists was in appledoc comment preprocessor which consumed single star and replaced them with double star markers so that text would be emitted in bold. That's actually a feature of appledoc which allows single stars be used for bold markers, but may break compatibility with Markdown as the result. As there's no reliable way of determining whether the user wants to have star delimited, I decided to go the route I had in my mind for some time now: introduce another command line switch that would prevent handling single stars. It's on/off solution, so not the best one, but everyone can choose at least... Also updated [online documentation](http://gentlebytes.com/appledoc-docs-examples-basic/index.html#compatibility) with example of using the new switch.

**Important:** As of this version on, single star handling is **off** by default! This may break backwards compatibility with some folks, but I feel it's better to keep as Markdown compatible for new people as possible...
  • Loading branch information...
commit e81e2f88bc3e27e793e08cfbb8c7b1e93039f6e1 1 parent 95429b0
@tomaz authored
View
2  AppledocTests-Info.plist
@@ -17,6 +17,6 @@
<key>CFBundleSignature</key>
<string>????</string>
<key>CFBundleVersion</key>
- <string>703</string>
+ <string>737</string>
</dict>
</plist>
View
11 Application/GBAppledocApplication.m
@@ -40,6 +40,7 @@
static NSString *kGBArgExitCodeThreshold = @"exit-threshold";
static NSString *kGBArgRepeatFirstParagraph = @"repeat-first-par";
+static NSString *kGBArgUseSingleStar = @"use-single-star";
static NSString *kGBArgKeepUndocumentedObjects = @"keep-undocumented-objects";
static NSString *kGBArgKeepUndocumentedMembers = @"keep-undocumented-members";
static NSString *kGBArgFindUndocumentedMembersDocumentation = @"search-undocumented-doc";
@@ -270,6 +271,7 @@ - (void)application:(DDCliApplication *)app willParseOptions:(DDGetoptLongParser
{ kGBArgKeepUndocumentedMembers, 0, DDGetoptNoArgument },
{ kGBArgFindUndocumentedMembersDocumentation, 0, DDGetoptNoArgument },
{ kGBArgRepeatFirstParagraph, 0, DDGetoptNoArgument },
+ { kGBArgUseSingleStar, 0, DDGetoptNoArgument },
{ kGBArgMergeCategoriesToClasses, 0, DDGetoptNoArgument },
{ kGBArgKeepMergedCategoriesSections, 0, DDGetoptNoArgument },
{ kGBArgPrefixMergedCategoriesSectionsWithCategoryName, 0, DDGetoptNoArgument },
@@ -402,6 +404,11 @@ - (void)validateSettingsAndArguments:(NSArray *)arguments {
else if (isDir)
ddprintf(@"WARN: --%@ path '%@' is a directory, file is required, ignoring!\n", kGBArgIndexDescPath, self.settings.indexDescriptionPath);
}
+
+ // If we're using backwards compatibility mode, warn about potential incompatibility with Markdown!
+ if (self.settings.useSingleStarForBold) {
+ ddprintf(@"WARN: --%@ may cause incompatibility with Markdown (* unordered lists etc.)", kGBArgUseSingleStar);
+ }
}
- (BOOL)validateTemplatesPath:(NSString *)path error:(NSError **)error {
@@ -664,6 +671,7 @@ - (void)setKeepUndocumentedObjects:(BOOL)value { self.settings.keepUndocumentedO
- (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)setUseSingleStar:(BOOL)value { self.settings.useSingleStarForBold = 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; }
@@ -672,6 +680,7 @@ - (void)setNoKeepUndocumentedObjects:(BOOL)value { self.settings.keepUndocumente
- (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)setNoUseSingleStar:(BOOL)value { self.settings.useSingleStarForBold = !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; }
@@ -784,6 +793,7 @@ - (void)printSettingsAndArguments:(NSArray *)arguments {
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", kGBArgUseSingleStar, PRINT_BOOL(self.settings.useSingleStarForBold));
ddprintf(@"--%@ = %@\n", kGBArgMergeCategoriesToClasses, PRINT_BOOL(self.settings.mergeCategoriesToClasses));
ddprintf(@"--%@ = %@\n", kGBArgKeepMergedCategoriesSections, PRINT_BOOL(self.settings.keepMergedCategoriesSections));
ddprintf(@"--%@ = %@\n", kGBArgPrefixMergedCategoriesSectionsWithCategoryName, PRINT_BOOL(self.settings.prefixMergedCategoriesSectionsWithCategoryName));
@@ -847,6 +857,7 @@ - (void)printHelp {
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(@" ", kGBArgUseSingleStar, @"", @"[b] Use single star for bold marker");
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");
View
6 Application/GBApplicationSettingsProvider.h
@@ -232,6 +232,12 @@ extern id kGBCustomDocumentIndexDescKey;
*/
@property (assign) BOOL repeatFirstParagraphForMemberDescription;
+/** 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.
+ */
+@property (assign) BOOL useSingleStarForBold;
+
/** 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.
View
2  Application/GBApplicationSettingsProvider.m
@@ -79,6 +79,7 @@ - (id)init {
self.installDocSet = YES;
self.publishDocSet = NO;
self.repeatFirstParagraphForMemberDescription = YES;
+ self.useSingleStarForBold = NO;
self.keepIntermediateFiles = NO;
self.cleanupOutputPathBeforeRunning = NO;
self.keepUndocumentedObjects = NO;
@@ -593,6 +594,7 @@ - (NSString *)versionIdentifier {
@synthesize docsetPackageFilename;
@synthesize repeatFirstParagraphForMemberDescription;
+@synthesize useSingleStarForBold;
@synthesize keepUndocumentedObjects;
@synthesize keepUndocumentedMembers;
@synthesize findUndocumentedMembersDocumentation;
View
4 Application/GBApplicationStringsProvider.m
@@ -138,8 +138,8 @@ - (NSDictionary *)appledocData {
if (!result) {
result = [[NSMutableDictionary alloc] init];
[result setObject:@"appledoc" forKey:@"tool"];
- [result setObject:@"2.0.4" forKey:@"version"];
- [result setObject:@"703" forKey:@"build"];
+ [result setObject:@"2.0.5" forKey:@"version"];
+ [result setObject:@"737" forKey:@"build"];
[result setObject:@"http://appledoc.gentlebytes.com" forKey:@"homepage"];
}
return result;
View
13 Processing/GBCommentsProcessor.m
@@ -426,7 +426,8 @@ - (NSString *)stringByPreprocessingString:(NSString *)string withFlags:(GBProces
if ([string length] == 0) return string;
// Formatting markers are fine, except *, which should be converted to **. To simplify cross refs detection, we handle all possible formatting markers though so we can search for cross refs within "clean" formatted text, without worrying about markers interfering with search. Note that we also handle "standard" Markdown nested formats and bold markers here, so that we properly handle cross references within.
- NSArray *components = [string arrayOfDictionariesByMatchingRegex:@"(?s:(\\*__|__\\*|\\*\\*_|_\\*\\*|\\*\\*\\*|___|\\*_|_\\*|\\*\\*|__|\\*|_|==!!==|`)(.+?)\\1)" withKeysAndCaptures:@"marker", 1, @"value", 2, nil];
+ NSString *pattern = @"(?s:(\\*__|__\\*|\\*\\*_|_\\*\\*|\\*\\*\\*|___|\\*_|_\\*|\\*\\*|__|\\*|_|==!!==|`)(.+?)\\1)";
+ NSArray *components = [string arrayOfDictionariesByMatchingRegex:pattern withKeysAndCaptures:@"marker", 1, @"value", 2, nil];
NSRange searchRange = NSMakeRange(0, [string length]);
NSMutableString *result = [NSMutableString stringWithCapacity:[string length]];
for (NSDictionary *component in components) {
@@ -448,9 +449,13 @@ - (NSString *)stringByPreprocessingString:(NSString *)string withFlags:(GBProces
NSString *markdownStartMarker = @"";
NSString *markdownEndMarker = nil;
if ([componentMarker isEqualToString:@"*"]) {
- GBLogDebug(@" - Found '%@' formatted as bold at %@...", [componentText normalizedDescription], self.currentSourceInfo);
- markdownStartMarker = [NSString stringWithFormat:@"**%@", self.components.appledocBoldStartMarker];
- markdownEndMarker = [NSString stringWithFormat:@"%@**", self.components.appledocBoldEndMarker];
+ if (self.settings.useSingleStarForBold) {
+ GBLogDebug(@" - Found '%@' formatted as bold at %@...", [componentText normalizedDescription], self.currentSourceInfo);
+ markdownStartMarker = [NSString stringWithFormat:@"**%@", self.components.appledocBoldStartMarker];
+ markdownEndMarker = [NSString stringWithFormat:@"%@**", self.components.appledocBoldEndMarker];
+ } else {
+ markdownStartMarker = componentMarker;
+ }
}
else if ([componentMarker isEqualToString:@"_"]) {
GBLogDebug(@" - Found '%@' formatted as italics at %@...", [componentText normalizedDescription], self.currentSourceInfo);
View
9 Testing/GBApplicationTesting.m
@@ -257,6 +257,15 @@ - (void)testRepeatFirstParagraph_shouldAssignValueToSettings {
assertThatBool(settings2.repeatFirstParagraphForMemberDescription, equalToBool(NO));
}
+- (void)testUseSingleStarForBold_shouldAssignValueToSettings {
+ // setup & execute
+ GBApplicationSettingsProvider *settings1 = [self settingsByRunningWithArgs:@"--use-single-star", nil];
+ GBApplicationSettingsProvider *settings2 = [self settingsByRunningWithArgs:@"--no-use-single-star", nil];
+ // verify
+ assertThatBool(settings1.useSingleStarForBold, equalToBool(YES));
+ assertThatBool(settings2.useSingleStarForBold, equalToBool(NO));
+}
+
- (void)testMergeCategoriesToClasses_shouldAssignValueToSettings {
// setup & execute
GBApplicationSettingsProvider *settings1 = [self settingsByRunningWithArgs:@"--merge-categories", nil];
View
31 Testing/GBCommentsProcessor-MarkdownTesting.m
@@ -117,7 +117,7 @@ - (void)testProcessCommentWithContextStore_markdown_shouldKeepInlineRemoteMember
[self assertComment:comment3 matchesLongDescMarkdown:@"[[Class value]](Classes/Class.html#//api/name/value)", nil];
}
-- (void)testProcessCommentWithContextStore_markdown_shouldProperlyFormatInlineLinksWithinFormattingMarkers {
+- (void)testProcessCommentWithContextStore_markdown_shouldProperlyFormatInlineLinksWithinStandardMarkdownFormattingMarkers {
// setup
GBStore *store = [self storeWithDefaultObjects];
GBCommentsProcessor *processor = [self defaultProcessor];
@@ -125,16 +125,43 @@ - (void)testProcessCommentWithContextStore_markdown_shouldProperlyFormatInlineLi
GBComment *comment2 = [GBComment commentWithStringValue:@"`Class(Category)`"];
GBComment *comment3 = [GBComment commentWithStringValue:@"*Protocol*"];
GBComment *comment4 = [GBComment commentWithStringValue:@"_Document_"];
+ GBComment *comment5 = [GBComment commentWithStringValue:@"**Protocol**"];
+ GBComment *comment6 = [GBComment commentWithStringValue:@"__Document__"];
// execute
[processor processComment:comment1 withContext:nil store:store];
[processor processComment:comment2 withContext:nil store:store];
[processor processComment:comment3 withContext:nil store:store];
[processor processComment:comment4 withContext:nil store:store];
+ [processor processComment:comment5 withContext:nil store:store];
+ [processor processComment:comment6 withContext:nil store:store];
// verify
[self assertComment:comment1 matchesLongDescMarkdown:@"[`Class`](Classes/Class.html)", nil];
[self assertComment:comment2 matchesLongDescMarkdown:@"[`Class(Category)`](Categories/Class(Category).html)", nil];
- [self assertComment:comment3 matchesLongDescMarkdown:@"**~!$[Protocol](Protocols/Protocol.html)$!~**", nil];
+ [self assertComment:comment3 matchesLongDescMarkdown:@"*[Protocol](Protocols/Protocol.html)*", nil];
[self assertComment:comment4 matchesLongDescMarkdown:@"_[Document](docs/Document.html)_", nil];
+ [self assertComment:comment5 matchesLongDescMarkdown:@"**[Protocol](Protocols/Protocol.html)**", nil];
+ [self assertComment:comment6 matchesLongDescMarkdown:@"__[Document](docs/Document.html)__", nil];
+}
+
+- (void)testProcessCommentWithContextStore_markdown_shouldProperlyFormatInlineLinksWithinCustomFormattingMarkers {
+ // setup
+ GBStore *store = [self storeWithDefaultObjects];
+ id settings1 = [GBTestObjectsRegistry realSettingsProvider];
+ [settings1 setEmbedCrossReferencesWhenProcessingMarkdown:NO];
+ [settings1 setUseSingleStarForBold:NO];
+ GBCommentsProcessor *processor1 = [GBCommentsProcessor processorWithSettingsProvider:settings1];
+ GBComment *comment1 = [GBComment commentWithStringValue:@"*Protocol*"];
+ id settings2 = [GBTestObjectsRegistry realSettingsProvider];
+ [settings2 setEmbedCrossReferencesWhenProcessingMarkdown:NO];
+ [settings2 setUseSingleStarForBold:YES];
+ GBCommentsProcessor *processor2 = [GBCommentsProcessor processorWithSettingsProvider:settings2];
+ GBComment *comment2 = [GBComment commentWithStringValue:@"*Protocol*"];
+ // execute
+ [processor1 processComment:comment1 withContext:nil store:store];
+ [processor2 processComment:comment2 withContext:nil store:store];
+ // verify
+ [self assertComment:comment1 matchesLongDescMarkdown:@"*[Protocol](Protocols/Protocol.html)*", nil];
+ [self assertComment:comment2 matchesLongDescMarkdown:@"**~!$[Protocol](Protocols/Protocol.html)$!~**", nil];
}
- (void)testProcessCommentWithContextStore_markdown_shouldProperlyFormatInlineLinksWhenEmbeddingIsTurnedOn {
View
21 Testing/GBCommentsProcessor-PreprocessingTesting.m
@@ -32,9 +32,12 @@ @implementation GBCommentsProcessorPreprocessingTesting
#pragma mark Formatting markers conversion
-- (void)testStringByPreprocessingString_shouldConvertAppledocBoldMarkersToTemporarySyntax {
+- (void)testStringByPreprocessingString_shouldConvertAppledocBoldMarkersToTemporarySyntaxIfRequested {
// setup
- GBCommentsProcessor *processor = [self defaultProcessor];
+ id settings = [GBTestObjectsRegistry realSettingsProvider];
+ [settings setEmbedCrossReferencesWhenProcessingMarkdown:NO];
+ [settings setUseSingleStarForBold:YES];
+ GBCommentsProcessor *processor = [GBCommentsProcessor processorWithSettingsProvider:settings];
// execute
NSString *result1 = [processor stringByPreprocessingString:@"*bold1* *bold text* * bolder text *" withFlags:0];
NSString *result2 = [processor stringByPreprocessingString:@"*bold1* Middle *bold text*" withFlags:0];
@@ -43,6 +46,20 @@ - (void)testStringByPreprocessingString_shouldConvertAppledocBoldMarkersToTempor
assertThat(result2, is(@"**~!$bold1$!~** Middle **~!$bold text$!~**"));
}
+- (void)testStringByPreprocessingString_shouldNotConvertAppledocBoldMarkersToTemporarySyntaxIfPrevented {
+ // setup
+ id settings = [GBTestObjectsRegistry realSettingsProvider];
+ [settings setEmbedCrossReferencesWhenProcessingMarkdown:NO];
+ [settings setUseSingleStarForBold:NO];
+ GBCommentsProcessor *processor = [GBCommentsProcessor processorWithSettingsProvider:settings];
+ // execute
+ NSString *result1 = [processor stringByPreprocessingString:@"*bold1* *bold text* * bolder text *" withFlags:0];
+ NSString *result2 = [processor stringByPreprocessingString:@"*bold1* Middle *bold text*" withFlags:0];
+ // verify
+ assertThat(result1, is(@"*bold1* *bold text* * bolder text *"));
+ assertThat(result2, is(@"*bold1* Middle *bold text*"));
+}
+
- (void)testStringByPreprocessingString_shouldLeaveItalicsMarkers {
// setup
GBCommentsProcessor *processor = [self defaultProcessor];
Please sign in to comment.
Something went wrong with that request. Please try again.