Heya, I made the html refs appledoc does generate mirror apple's style. #295

Merged
merged 3 commits into from Jan 6, 2013
@@ -39,6 +39,7 @@
static NSString *kGBArgCreateDocSet = @"create-docset";
static NSString *kGBArgInstallDocSet = @"install-docset";
static NSString *kGBArgPublishDocSet = @"publish-docset";
+static NSString *kGBArgHTMLAnchorFormat = @"html-anchors";
static NSString *kGBArgKeepIntermediateFiles = @"keep-intermediate-files";
static NSString *kGBArgExitCodeThreshold = @"exit-threshold";
@@ -266,6 +267,7 @@ - (void)application:(DDCliApplication *)app willParseOptions:(DDGetoptLongParser
{ kGBArgCreateDocSet, 'd', DDGetoptNoArgument },
{ kGBArgInstallDocSet, 'n', DDGetoptNoArgument },
{ kGBArgPublishDocSet, 'u', DDGetoptNoArgument },
+ { kGBArgHTMLAnchorFormat, 0, DDGetoptRequiredArgument },
{ GBNoArg(kGBArgCreateHTML), 0, DDGetoptNoArgument },
{ GBNoArg(kGBArgCreateDocSet), 0, DDGetoptNoArgument },
{ GBNoArg(kGBArgInstallDocSet), 0, DDGetoptNoArgument },
@@ -765,6 +767,9 @@ - (void)setPublishDocset:(BOOL)value {
// self.settings.installDocSet = YES;
}
}
+- (void)setHtmlAnchors:(NSString *)value {
+ self.settings.htmlAnchorFormat = GBHTMLAnchorFormatFromNSString(value);
+}
- (void)setNoCleanOutput:(BOOL)value { self.settings.cleanupOutputPathBeforeRunning = !value; }
- (void)setNoCreateHtml:(BOOL)value { [self setCreateHtml:!value]; }
- (void)setNoCreateDocset:(BOOL)value { [self setCreateDocset:!value]; }
@@ -905,6 +910,7 @@ - (void)printSettingsAndArguments:(NSArray *)arguments {
ddprintf(@"--%@ = %@\n", kGBArgCreateDocSet, PRINT_BOOL(self.settings.createDocSet));
ddprintf(@"--%@ = %@\n", kGBArgInstallDocSet, PRINT_BOOL(self.settings.installDocSet));
ddprintf(@"--%@ = %@\n", kGBArgPublishDocSet, PRINT_BOOL(self.settings.publishDocSet));
+ ddprintf(@"--%@ = %@\n", kGBArgHTMLAnchorFormat, NSStringFromGBHTMLAnchorFormat(self.settings.htmlAnchorFormat));
ddprintf(@"--%@ = %@\n", kGBArgKeepIntermediateFiles, PRINT_BOOL(self.settings.keepIntermediateFiles));
ddprintf(@"--%@ = %@\n", kGBArgKeepUndocumentedObjects, PRINT_BOOL(self.settings.keepUndocumentedObjects));
ddprintf(@"--%@ = %@\n", kGBArgKeepUndocumentedMembers, PRINT_BOOL(self.settings.keepUndocumentedMembers));
@@ -969,6 +975,7 @@ - (void)printHelp {
PRINT_USAGE(@"-d,", kGBArgCreateDocSet, @"", @"[b] Create documentation set");
PRINT_USAGE(@"-n,", kGBArgInstallDocSet, @"", @"[b] Install documentation set to Xcode");
PRINT_USAGE(@"-u,", kGBArgPublishDocSet, @"", @"[b] Prepare DocSet for publishing");
+ PRINT_USAGE(@" ", kGBArgHTMLAnchorFormat, @"<string>", @"[*] The html anchor format to use in DocSet HTML.");
PRINT_USAGE(@" ", kGBArgCleanOutput, @"", @"[b] Remove contents of output path before starting !!CAUTION!!");
ddprintf(@"\n");
ddprintf(@"OPTIONS\n");
@@ -13,6 +13,15 @@
extern id kGBCustomDocumentIndexDescKey;
+typedef enum
+{
+ GBHTMLAnchorFormatAppleDoc = 0,
+ GBHTMLAnchorFormatApple
+} GBHTMLAnchorFormat;
+
+GBHTMLAnchorFormat GBHTMLAnchorFormatFromNSString(NSString *formatString);
+NSString *NSStringFromGBHTMLAnchorFormat(GBHTMLAnchorFormat format);
+
#pragma mark -
/** Main application settings provider.
@@ -213,6 +222,16 @@ extern id kGBCustomDocumentIndexDescKey;
*/
@property (assign) BOOL publishDocSet;
+/** Specifies the format docsets should use for their html anchors.
+
+ If `appledoc`, docset HTML files will use the format `//api/name/symbol_name` for anchor names.
+
+ If `apple`, docset HTML files will use the format `//apple_ref/occ/symbol_type/parent_symbol/symbol_name/`.
+
+ @see createDocSet
+ */
+@property (assign) GBHTMLAnchorFormat htmlAnchorFormat;
+
/** Specifies whether intermediate files should be kept in `outputPath` or not.
If `YES`, all intermediate files (i.e. HTML files and documentation set files) are kept in output path. If `NO`, only final results are kept. This setting not only affects how the files are being handled, it also affects performance. If intermediate files are not kept, appledoc moves files between various generation phases, otherwise it copies them. So it's prefferable to leave this option to `NO`. This option only affects output files, input source files are always left intact!
@@ -28,6 +28,24 @@
NSString *kGBCustomDocumentIndexDescKey = @"index-description";
+GBHTMLAnchorFormat GBHTMLAnchorFormatFromNSString(NSString *formatString) {
+ NSString *lowercaseFormatString = [formatString lowercaseString];
+ if ([lowercaseFormatString isEqualToString:@"apple"]) {
+ return GBHTMLAnchorFormatApple;
+ }
+ // We default to appledoc format if the option is not recognised
+ return GBHTMLAnchorFormatAppleDoc;
+}
+
+NSString *NSStringFromGBHTMLAnchorFormat(GBHTMLAnchorFormat format) {
+ switch (format) {
+ case GBHTMLAnchorFormatAppleDoc:
+ return @"appledoc";
+ case GBHTMLAnchorFormatApple:
+ return @"apple";
+ }
+}
+
#pragma mark -
@interface GBApplicationSettingsProvider ()
@@ -83,6 +101,7 @@ - (id)init {
self.createDocSet = YES;
self.installDocSet = YES;
self.publishDocSet = NO;
+ self.htmlAnchorFormat = GBHTMLAnchorFormatAppleDoc;
self.repeatFirstParagraphForMemberDescription = YES;
self.preprocessHeaderDoc = NO;
self.printInformationBlockTitles = YES;
@@ -373,7 +392,12 @@ - (NSString *)htmlReferenceForMember:(GBModelBase *)member prefixedWith:(NSStrin
NSParameterAssert(prefix != nil);
if ([member isKindOfClass:[GBMethodData class]]) {
GBMethodData *method = (GBMethodData *)member;
- return [NSString stringWithFormat:@"%@//api/name/%@", prefix, method.methodSelector];
+ switch (htmlAnchorFormat) {
+ case GBHTMLAnchorFormatApple:
+ return [NSString stringWithFormat:@"%@//apple_ref/occ/%@/%@/%@", prefix, [method methodTypeString], [method parentObject], method.methodSelector];
+ case GBHTMLAnchorFormatAppleDoc:
+ return [NSString stringWithFormat:@"%@//api/name/%@", prefix, method.methodSelector];
+ }
}
return @"";
}
@@ -623,6 +647,7 @@ - (NSString *)versionIdentifier {
@synthesize createDocSet;
@synthesize installDocSet;
@synthesize publishDocSet;
+@synthesize htmlAnchorFormat;
@synthesize keepIntermediateFiles;
@synthesize cleanupOutputPathBeforeRunning;
@synthesize treatDocSetIndexingErrorsAsFatals;
View
@@ -119,6 +119,10 @@ typedef NSUInteger GBMethodType;
*/
@property (retain) GBMethodSectionData *methodSection;
+/** A string representing the type of the method
+ */
+@property (readonly) NSString *methodTypeString;
+
///---------------------------------------------------------------------------------------
/// @name Helper properties
///---------------------------------------------------------------------------------------
View
@@ -10,6 +10,8 @@
#import "GBMethodArgument.h"
#import "GBMethodSectionData.h"
#import "GBMethodData.h"
+#import "GBClassData.h"
+#import "GBCategoryData.h"
#import "RegexKitLite.h"
@interface GBMethodData ()
@@ -365,6 +367,21 @@ - (NSString *)description {
#pragma mark Properties
+- (NSString *)methodTypeString {
+ BOOL isInterfaceParent = (![self.parentObject isKindOfClass:[GBClassData class]] &&
+ ![self.parentObject isKindOfClass:[GBCategoryData class]]);
+ switch (self.methodType)
+ {
+ case GBMethodTypeClass:
+ return isInterfaceParent ? @"intfcm" : @"clm";
+ case GBMethodTypeInstance:
+ return isInterfaceParent ? @"intfm" : @"instm";
+ case GBMethodTypeProperty:
+ return isInterfaceParent ? @"intfp" : @"instp";
+ }
+ return @"";
+}
+
- (BOOL)isInstanceMethod {
return (self.methodType == GBMethodTypeInstance);
}
@@ -167,8 +167,11 @@ - (void)testHtmlReferenceNameForObject_shouldReturnProperValueForDocuments {
- (void)testHtmlReferenceNameForObject_shouldReturnProperValueForMethods {
// setup
- GBApplicationSettingsProvider *settings = [GBApplicationSettingsProvider provider];
- settings.outputPath = @"anything :)";
+ GBApplicationSettingsProvider *settings1 = [GBApplicationSettingsProvider provider];
+ GBApplicationSettingsProvider *settings2 = [GBApplicationSettingsProvider provider];
+ settings1.outputPath = @"anything :)";
+ settings2.outputPath = @"anything :)";
+ settings2.htmlAnchorFormat = GBHTMLAnchorFormatApple;
GBMethodArgument *argument = [GBMethodArgument methodArgumentWithName:@"method"];
GBMethodData *method1 = [GBTestObjectsRegistry instanceMethodWithArguments:argument, nil];
GBMethodData *method2 = [GBTestObjectsRegistry instanceMethodWithNames:@"doSomething", @"withVars", nil];
@@ -178,47 +181,65 @@ - (void)testHtmlReferenceNameForObject_shouldReturnProperValueForMethods {
[class.methods registerMethod:method2];
[class.methods registerMethod:property];
// execute & verify
- assertThat([settings htmlReferenceNameForObject:method1], is(@"//api/name/method"));
- assertThat([settings htmlReferenceNameForObject:method2], is(@"//api/name/doSomething:withVars:"));
- assertThat([settings htmlReferenceNameForObject:property], is(@"//api/name/value"));
+ assertThat([settings1 htmlReferenceNameForObject:method1], is(@"//api/name/method"));
+ assertThat([settings1 htmlReferenceNameForObject:method2], is(@"//api/name/doSomething:withVars:"));
+ assertThat([settings1 htmlReferenceNameForObject:property], is(@"//api/name/value"));
+ assertThat([settings2 htmlReferenceNameForObject:method1], is(@"//apple_ref/occ/instm/Class/method"));
+ assertThat([settings2 htmlReferenceNameForObject:method2], is(@"//apple_ref/occ/instm/Class/doSomething:withVars:"));
+ assertThat([settings2 htmlReferenceNameForObject:property], is(@"//apple_ref/occ/instp/Class/value"));
}
#pragma mark HTML href references handling - index
- (void)testHtmlReferenceForObjectFromSource_shouldReturnProperValueForClassFromIndex {
// setup
- GBApplicationSettingsProvider *settings = [GBApplicationSettingsProvider provider];
- settings.outputPath = @"anything :)";
+ GBApplicationSettingsProvider *settings1 = [GBApplicationSettingsProvider provider];
+ GBApplicationSettingsProvider *settings2 = [GBApplicationSettingsProvider provider];
+ settings1.outputPath = @"anything :)";
+ settings2.outputPath = @"anything :)";
+ settings2.htmlAnchorFormat = GBHTMLAnchorFormatApple;
GBClassData *class = [GBClassData classDataWithName:@"Class"];
GBMethodData *method = [GBTestObjectsRegistry instanceMethodWithNames:@"method", nil];
[class.methods registerMethod:method];
// execute & verify
- assertThat([settings htmlReferenceForObject:class fromSource:nil], is(@"Classes/Class.html"));
- assertThat([settings htmlReferenceForObject:method fromSource:nil], is(@"Classes/Class.html#//api/name/method:"));
+ assertThat([settings1 htmlReferenceForObject:class fromSource:nil], is(@"Classes/Class.html"));
+ assertThat([settings1 htmlReferenceForObject:method fromSource:nil], is(@"Classes/Class.html#//api/name/method:"));
+ assertThat([settings2 htmlReferenceForObject:class fromSource:nil], is(@"Classes/Class.html"));
+ assertThat([settings2 htmlReferenceForObject:method fromSource:nil], is(@"Classes/Class.html#//apple_ref/occ/instm/Class/method:"));
}
- (void)testHtmlReferenceForObjectFromSource_shouldReturnProperValueForCategoryFromIndex {
// setup
- GBApplicationSettingsProvider *settings = [GBApplicationSettingsProvider provider];
- settings.outputPath = @"anything :)";
+ GBApplicationSettingsProvider *settings1 = [GBApplicationSettingsProvider provider];
+ GBApplicationSettingsProvider *settings2 = [GBApplicationSettingsProvider provider];
+ settings1.outputPath = @"anything :)";
+ settings2.outputPath = @"anything :)";
+ settings2.htmlAnchorFormat = GBHTMLAnchorFormatApple;
GBCategoryData *category = [GBCategoryData categoryDataWithName:@"Category" className:@"Class"];
GBMethodData *method = [GBTestObjectsRegistry instanceMethodWithNames:@"method", nil];
[category.methods registerMethod:method];
// execute & verify
- assertThat([settings htmlReferenceForObject:category fromSource:nil], is(@"Categories/Class+Category.html"));
- assertThat([settings htmlReferenceForObject:method fromSource:nil], is(@"Categories/Class+Category.html#//api/name/method:"));
+ assertThat([settings1 htmlReferenceForObject:category fromSource:nil], is(@"Categories/Class+Category.html"));
+ assertThat([settings1 htmlReferenceForObject:method fromSource:nil], is(@"Categories/Class+Category.html#//api/name/method:"));
+ assertThat([settings2 htmlReferenceForObject:category fromSource:nil], is(@"Categories/Class+Category.html"));
+ assertThat([settings2 htmlReferenceForObject:method fromSource:nil], is(@"Categories/Class+Category.html#//apple_ref/occ/instm/Class(Category)/method:"));
}
- (void)testHtmlReferenceForObjectFromSource_shouldReturnProperValueForProtocolFromIndex {
// setup
- GBApplicationSettingsProvider *settings = [GBApplicationSettingsProvider provider];
- settings.outputPath = @"anything :)";
+ GBApplicationSettingsProvider *settings1 = [GBApplicationSettingsProvider provider];
+ GBApplicationSettingsProvider *settings2 = [GBApplicationSettingsProvider provider];
+ settings1.outputPath = @"anything :)";
+ settings2.outputPath = @"anything :)";
+ settings2.htmlAnchorFormat = GBHTMLAnchorFormatApple;
GBProtocolData *protocol = [GBProtocolData protocolDataWithName:@"Protocol"];
GBMethodData *method = [GBTestObjectsRegistry instanceMethodWithNames:@"method", nil];
[protocol.methods registerMethod:method];
// execute & verify
- assertThat([settings htmlReferenceForObject:protocol fromSource:nil], is(@"Protocols/Protocol.html"));
- assertThat([settings htmlReferenceForObject:method fromSource:nil], is(@"Protocols/Protocol.html#//api/name/method:"));
+ assertThat([settings1 htmlReferenceForObject:protocol fromSource:nil], is(@"Protocols/Protocol.html"));
+ assertThat([settings1 htmlReferenceForObject:method fromSource:nil], is(@"Protocols/Protocol.html#//api/name/method:"));
+ assertThat([settings2 htmlReferenceForObject:protocol fromSource:nil], is(@"Protocols/Protocol.html"));
+ assertThat([settings2 htmlReferenceForObject:method fromSource:nil], is(@"Protocols/Protocol.html#//apple_ref/occ/intfm/Protocol/method:"));
}
- (void)testHtmlReferenceForObjectFromSource_shouldReturnProperValueForDocumentFromIndex {
@@ -346,44 +367,61 @@ - (void)testHtmlReferenceForObjectFromSource_shouldReturnProperValueForCustomDoc
- (void)testHtmlReferenceForObjectFromSource_shouldReturnProperValueForTopLevelObjectToItsMemberReference {
// setup
- GBApplicationSettingsProvider *settings = [GBApplicationSettingsProvider provider];
- settings.outputPath = @"anything :)";
+ GBApplicationSettingsProvider *settings1 = [GBApplicationSettingsProvider provider];
+ GBApplicationSettingsProvider *settings2 = [GBApplicationSettingsProvider provider];
+ settings1.outputPath = @"anything :)";
+ settings2.outputPath = @"anything :)";
+ settings2.htmlAnchorFormat = GBHTMLAnchorFormatApple;
GBClassData *class = [GBClassData classDataWithName:@"Class"];
GBMethodData *method = [GBTestObjectsRegistry propertyMethodWithArgument:@"value"];
[class.methods registerMethod:method];
// execute & verify
- assertThat([settings htmlReferenceForObject:method fromSource:class], is(@"#//api/name/value"));
- assertThat([settings htmlReferenceForObject:class fromSource:method], is(@"Class.html"));
+ assertThat([settings1 htmlReferenceForObject:method fromSource:class], is(@"#//api/name/value"));
+ assertThat([settings1 htmlReferenceForObject:class fromSource:method], is(@"Class.html"));
+ assertThat([settings2 htmlReferenceForObject:method fromSource:class], is(@"#//apple_ref/occ/instp/Class/value"));
+ assertThat([settings2 htmlReferenceForObject:class fromSource:method], is(@"Class.html"));
}
- (void)testHtmlReferenceForObjectFromSource_shouldReturnProperValueForTopLevelObjectToSameTypeRemoteMemberReference {
// setup
- GBApplicationSettingsProvider *settings = [GBApplicationSettingsProvider provider];
- settings.outputPath = @"anything :)";
+ GBApplicationSettingsProvider *settings1 = [GBApplicationSettingsProvider provider];
+ GBApplicationSettingsProvider *settings2 = [GBApplicationSettingsProvider provider];
+ settings1.outputPath = @"anything :)";
+ settings2.outputPath = @"anything :)";
+ settings2.htmlAnchorFormat = GBHTMLAnchorFormatApple;
GBClassData *class1 = [GBClassData classDataWithName:@"Class1"];
GBClassData *class2 = [GBClassData classDataWithName:@"Class2"];
GBMethodData *method = [GBTestObjectsRegistry propertyMethodWithArgument:@"value"];
[class1.methods registerMethod:method];
// execute & verify
- assertThat([settings htmlReferenceForObject:method fromSource:class2], is(@"../Classes/Class1.html#//api/name/value"));
- assertThat([settings htmlReferenceForObject:method fromSource:class1], is(@"#//api/name/value"));
- assertThat([settings htmlReferenceForObject:class1 fromSource:method], is(@"Class1.html"));
- assertThat([settings htmlReferenceForObject:class2 fromSource:method], is(@"../Classes/Class2.html"));
+ assertThat([settings1 htmlReferenceForObject:method fromSource:class2], is(@"../Classes/Class1.html#//api/name/value"));
+ assertThat([settings1 htmlReferenceForObject:method fromSource:class1], is(@"#//api/name/value"));
+ assertThat([settings1 htmlReferenceForObject:class1 fromSource:method], is(@"Class1.html"));
+ assertThat([settings1 htmlReferenceForObject:class2 fromSource:method], is(@"../Classes/Class2.html"));
+ assertThat([settings2 htmlReferenceForObject:method fromSource:class2], is(@"../Classes/Class1.html#//apple_ref/occ/instp/Class1/value"));
+ assertThat([settings2 htmlReferenceForObject:method fromSource:class1], is(@"#//apple_ref/occ/instp/Class1/value"));
+ assertThat([settings2 htmlReferenceForObject:class1 fromSource:method], is(@"Class1.html"));
+ assertThat([settings2 htmlReferenceForObject:class2 fromSource:method], is(@"../Classes/Class2.html"));
}
- (void)testHtmlReferenceForObjectFromSource_shouldReturnProperValueForTopLevelObjectToDifferentTypeRemoteMemberReference {
// setup
- GBApplicationSettingsProvider *settings = [GBApplicationSettingsProvider provider];
- settings.outputPath = @"anything :)";
+ GBApplicationSettingsProvider *settings1 = [GBApplicationSettingsProvider provider];
+ GBApplicationSettingsProvider *settings2 = [GBApplicationSettingsProvider provider];
+ settings1.outputPath = @"anything :)";
+ settings2.outputPath = @"anything :)";
+ settings2.htmlAnchorFormat = GBHTMLAnchorFormatApple;
GBClassData *class = [GBClassData classDataWithName:@"Class"];
GBCategoryData *protocol = [GBProtocolData protocolDataWithName:@"Protocol"];
GBMethodData *method1 = [GBTestObjectsRegistry propertyMethodWithArgument:@"value1"];
GBMethodData *method2 = [GBTestObjectsRegistry propertyMethodWithArgument:@"value2"];
[class.methods registerMethod:method1];
[protocol.methods registerMethod:method2];
// execute & verify
- assertThat([settings htmlReferenceForObject:method1 fromSource:protocol], is(@"../Classes/Class.html#//api/name/value1"));
- assertThat([settings htmlReferenceForObject:method2 fromSource:class], is(@"../Protocols/Protocol.html#//api/name/value2"));
+ assertThat([settings1 htmlReferenceForObject:method1 fromSource:protocol], is(@"../Classes/Class.html#//api/name/value1"));
+ assertThat([settings1 htmlReferenceForObject:method2 fromSource:class], is(@"../Protocols/Protocol.html#//api/name/value2"));
+ assertThat([settings2 htmlReferenceForObject:method1 fromSource:protocol], is(@"../Classes/Class.html#//apple_ref/occ/instp/Class/value1"));
+ assertThat([settings2 htmlReferenceForObject:method2 fromSource:class], is(@"../Protocols/Protocol.html#//apple_ref/occ/intfp/Protocol/value2"));
}
#pragma mark Template files handling
Oops, something went wrong.