Merge branch 'development'

AppledocTests-Info.plist

@@ -17,6 +17,6 @@
 	<key>CFBundleSignature</key>
 	<string>????</string>
 	<key>CFBundleVersion</key>
-	<string>566</string>
+	<string>632</string>
 </dict>
 </plist>

Application/GBAppledocApplication.h

@@ -9,7 +9,7 @@
 #import <Foundation/Foundation.h>
 #import "DDCliApplication.h"
 
-/** The appledoc application handler. 
+/** The appledoc application handler.
  
  This is the principal tool class. It represents the entry point for the application. The main promises of the class are parsing and validating of command line arguments and initiating documentation generation. Generation is divided into several distinct phases:
  

Application/GBAppledocApplication.m

@@ -472,8 +472,8 @@ - (void)setNoInstallDocset:(BOOL)value { self.settings.installDocSet = !value; }
 - (void)setNoPublishDocset:(BOOL)value { self.settings.publishDocSet = !value; }
 
 - (void)setCrossrefFormat:(NSString *)value { self.settings.commentComponents.crossReferenceMarkersTemplate = value; }
-- (void)setExplicitCrossref:(BOOL)value { self.settings.commentComponents.crossReferenceMarkersTemplate = @"<%@>"; }
-- (void)setNoExplicitCrossref:(BOOL)value { self.settings.commentComponents.crossReferenceMarkersTemplate = @"<?%@>?"; }
+- (void)setExplicitCrossref:(BOOL)value { self.settings.commentComponents.crossReferenceMarkersTemplate = value ? @"<%@>" : @"<?%@>?"; }
+- (void)setNoExplicitCrossref:(BOOL)value { [self setExplicitCrossref:!value]; }
 
 - (void)setKeepIntermediateFiles:(BOOL)value { self.settings.keepIntermediateFiles = value;}
 - (void)setKeepUndocumentedObjects:(BOOL)value { self.settings.keepUndocumentedObjects = value; }

Application/GBApplicationSettingsProvider.h

@@ -154,7 +154,7 @@
 /// @name Behavior handling
 ///---------------------------------------------------------------------------------------
 
-/* Indicates whether HTML files should be generated or not.
+/** Indicates whether HTML files should be generated or not.
  
  If `YES`, HTML files are generated in `outputPath` from parsed and processed data. If `NO`, input files are parsed and processed, but nothing is generated.
  
@@ -278,6 +278,12 @@
  */
 @property (assign) BOOL prefixMergedCategoriesSectionsWithCategoryName;
 
+/** Indicates whteher local methods and properties cross references texts should be prefixed when used in related items list.
+ 
+ If `YES`, instance methods are prefixed with `-`, class methods with `+` and properties with `@property` when used as cross reference in related items list (i.e. see also section for methods). If `NO`, no prefix is used.
+ */
+@property (assign) BOOL prefixLocalMembersInRelatedItemsList;
+
 ///---------------------------------------------------------------------------------------
 /// @name Warnings handling
 ///---------------------------------------------------------------------------------------
@@ -328,10 +334,58 @@
 /// @name Application-wide HTML helpers
 ///---------------------------------------------------------------------------------------
 
+/** Specifies whether cross references should be embedded to special strings when processing Markdown.
+ 
+ This should be left to default value, however it's useful to prevent embedding for unit testing.
+ 
+ @see stringByEmbeddingCrossReference:
+ */
+@property (assign) BOOL embedCrossReferencesWhenProcessingMarkdown;
+
+/** Returns a new string with the given Markdown reference embedded in special markers.
+ 
+ This should be used for all generated cross references, so that we can later detect them when converting HTML with `stringByConvertingMarkdownToHTML:`.
+ 
+ @warning *Important:* Behavior of this method depends on `embedCrossReferencesWhenProcessingMarkdown` value. If it's `YES`, strings are embedded, otherwise the given value is returned without enmbedding.
+ 
+ @param value The string to embedd.
+ @return Returns embedded string.
+ @see stringByConvertingMarkdownToHTML:
+ @see embedCrossReferencesWhenProcessingMarkdown
+ */
+- (NSString *)stringByEmbeddingCrossReference:(NSString *)value;
+
+/** Returns a new string containing HTML representation of the given Markdown string.
+ 
+ This is the main method for converting Markdown to HTML. It works in two phases: first the Markdown engine is asked to convert the given string to HTML, then the string is cleaned up so that it contains proper HTML code. Cleaning up phase consists of:
+ 
+ - Cleaning any appledoc generated cross reference inside `<pre>` blocks. Markdown doesn't process links here, so in case appledoc detects known object and converts it to Markdown style link, the Markdown syntaxt is left untouched. This phase makes sure all such occurences are cleaned up to original text. This is only invoked if `embedCrossReferencesWhenProcessingMarkdown` value is `YES`!
+ 
+ @param markdown Markdown source string to convert.
+ @return Returns converted string.
+ @see stringByEmbeddingCrossReference:
+ @see stringByConvertingMarkdownToText:
+ @see stringByEscapingHTML:
+ */
+- (NSString *)stringByConvertingMarkdownToHTML:(NSString *)markdown;
+
+/** Returns a new string containing text representation of the given Markdown string.
+ 
+ The main responsibility of this method is to strip Markdown links to names only to give text more readability when used in Xcode quick help. Although the name suggests this can handle Markdown strings, it's intended to be given appledoc comment string, prior to passing it to `GBCommentsProcessor`.
+ 
+ @param markdown Markdown source string to convert.
+ @return Returns converted string.
+ @see stringByConvertingMarkdownToHTML:
+ @see stringByEscapingHTML:
+ */
+- (NSString *)stringByConvertingMarkdownToText:(NSString *)markdown;
+
 /** Returns a new string by escaping the given HTML.
  
  @param string HTML string to escape.
  @return Returns escaped HTML string.
+ @see stringByConvertingMarkdownToHTML:
+ @see stringByConvertingMarkdownToText:
  */
 - (NSString *)stringByEscapingHTML:(NSString *)string;
 

Application/GBApplicationSettingsProvider.m

@@ -6,6 +6,7 @@
 //  Copyright (C) 2010, Gentle Bytes. All rights reserved.
 //
 
+#include "mkdio.h"
 #import <objc/runtime.h>
 #import "RegexKitLite.h"
 #import "GBDataObjects.h"
@@ -76,9 +77,13 @@ - (id)init {
 		self.keepUndocumentedObjects = NO;
 		self.keepUndocumentedMembers = NO;
 		self.findUndocumentedMembersDocumentation = YES;
+
 		self.mergeCategoriesToClasses = YES;
 		self.keepMergedCategoriesSections = NO;
 		self.prefixMergedCategoriesSectionsWithCategoryName = NO;
+
+		self.prefixLocalMembersInRelatedItemsList = YES;
+		self.embedCrossReferencesWhenProcessingMarkdown = YES;
 
 		self.warnOnMissingOutputPathArgument = YES;
 		self.warnOnMissingCompanyIdentifier = YES;
@@ -144,6 +149,91 @@ - (void)replaceAllOccurencesOfPlaceholderStringsInSettingsValues {
 
 #pragma mark Common HTML handling
 
+- (NSString *)stringByEmbeddingCrossReference:(NSString *)value {
+	if (!self.embedCrossReferencesWhenProcessingMarkdown) return value;
+	return [NSString stringWithFormat:@"~!@%@@!~", value];
+}
+
+- (NSString *)stringByConvertingMarkdownToHTML:(NSString *)markdown {
+	// First pass the markdown to discount to get it converted to HTML.
+	NSString *result = nil;
+	MMIOT *document = mkd_string((char *)[markdown cStringUsingEncoding:NSUTF8StringEncoding], (int)[markdown length], 0);
+	mkd_compile(document, 0);
+	char *html = NULL;
+	int size = mkd_document(document, &html);
+	if (size <= 0) {
+		GBLogWarn(@"Failed converting markdown '%@' to HTML!", [markdown normalizedDescription]);
+	} else {
+		result = [NSString stringWithCString:html encoding:NSASCIIStringEncoding];
+	}
+	mkd_cleanup(document);
+
+	// Post process embedded cross references if needed.
+	if (!self.embedCrossReferencesWhenProcessingMarkdown) return result;
+	__block BOOL insideExampleBlock = NO;
+	NSString *regex = @"<pre>|</pre>|~!@(.+?)@!~";
+	NSString *clean = [result stringByReplacingOccurrencesOfRegex:regex usingBlock:^NSString *(NSInteger captureCount, NSString *const *capturedStrings, const NSRange *capturedRanges, volatile BOOL *const stop) {
+		// Change flag when inside example block - we need to handle strings differently there!
+		NSString *matchedText = capturedStrings[0];
+		if ([matchedText isEqualToString:@"<pre>"]) {
+			insideExampleBlock = YES;
+			return matchedText;
+		} else if ([matchedText isEqualToString:@"</pre>"]) {
+			insideExampleBlock = NO;
+			return matchedText;
+		}
+
+		// If outside example block, just return cross reference without embedded prefix and suffix!
+		NSString *linkText = capturedStrings[1];
+		if (!insideExampleBlock) return linkText;
+
+		// If inside example block, we need to extract description from Markdown text and only use that part! If we don't match Markdown style reference, just use whole text...
+		NSArray *components = [linkText captureComponentsMatchedByRegex:self.commentComponents.markdownInlineLinkRegex];
+		if ([components count] < 1) return linkText;
+		return [components objectAtIndex:1];
+	}];
+	return clean;
+}
+
+- (NSString *)stringByConvertingMarkdownToText:(NSString *)markdown {
+	NSString *result = markdown;
+
+	// Clean Markdown inline links.
+	result = [result stringByReplacingOccurrencesOfRegex:self.commentComponents.markdownInlineLinkRegex usingBlock:^NSString *(NSInteger captureCount, NSString *const *capturedStrings, const NSRange *capturedRanges, volatile BOOL *const stop) {
+		return capturedStrings[1];
+	}];
+
+	// Clean formatting directives. Couldn't find single regex matcher for cleaning up all cases, so ended up in doing several phases and finally repeating the last one for any remaining cases... This makes unit tests pass...
+	result = [result stringByReplacingOccurrencesOfRegex:@"(\\*\\*\\*|___|\\*\\*_|_\\*\\*|\\*__|__\\*)(.+?)\\1" usingBlock:^NSString *(NSInteger captureCount, NSString *const *capturedStrings, const NSRange *capturedRanges, volatile BOOL *const stop) {
+		return capturedStrings[2];
+	}];
+	result = [result stringByReplacingOccurrencesOfRegex:@"(\\*\\*|__|\\*_|_\\*)(.+?)\\1" usingBlock:^NSString *(NSInteger captureCount, NSString *const *capturedStrings, const NSRange *capturedRanges, volatile BOOL *const stop) {
+		return capturedStrings[2];
+	}];
+	result = [result stringByReplacingOccurrencesOfRegex:@"([*_`])(.+?)\\1" usingBlock:^NSString *(NSInteger captureCount, NSString *const *capturedStrings, const NSRange *capturedRanges, volatile BOOL *const stop) {
+		return capturedStrings[2];
+	}];
+	result = [result stringByReplacingOccurrencesOfRegex:@"([*_`])(.+?)\\1" usingBlock:^NSString *(NSInteger captureCount, NSString *const *capturedStrings, const NSRange *capturedRanges, volatile BOOL *const stop) {
+		return capturedStrings[2];
+	}];
+
+	// Convert hard coded HTML anchor links as these may cause problems with docsetutil. Basically we get address and description and output only description if found. Otherwise we use address.
+	NSString *anchorRegex = @"<a\\s+href\\s*=\\s*([\"'])([^\\1]*)[\"']\\s*(?:(?:>([^>]*)</a>)|(?:/>))";
+	result = [result stringByReplacingOccurrencesOfRegex:anchorRegex usingBlock:^NSString *(NSInteger captureCount, NSString *const *capturedStrings, const NSRange *capturedRanges, volatile BOOL *const stop) {
+		if (captureCount < 2) return capturedStrings[0];
+		if (captureCount < 3) return capturedStrings[2];
+		NSString *description = capturedStrings[3];
+		if ([description length] > 0) return description;
+		return capturedStrings[2];
+	}];
+
+	// Remove embedded preix/suffix if needed.
+	if (!self.embedCrossReferencesWhenProcessingMarkdown) return result;
+	result = [result stringByReplacingOccurrencesOfString:@"~!@" withString:@""];
+	result = [result stringByReplacingOccurrencesOfString:@"@!~" withString:@""];
+	return result;
+}
+
 - (NSString *)stringByEscapingHTML:(NSString *)string {
 	// Copied directly from GRMustache's GRMustacheVariableElement.m...
 	NSMutableString *result = [NSMutableString stringWithCapacity:5 + ceilf(string.length * 1.1)];
@@ -319,6 +409,12 @@ - (NSString *)outputPathForObject:(id)object withExtension:(NSString *)extension
 		NSString *subpath = [document.subpathOfDocument stringByDeletingLastPathComponent];
 		NSString *filename = [self outputFilenameForTemplatePath:document.pathOfDocument];
 		filename = [filename stringByDeletingPathExtension];
+
+		// If the document is included as part of a directory structure, we should use subdir, otherwise just leave the filename.
+		if (![document.basePathOfDocument isEqualToString:document.pathOfDocument]) {
+			NSString *includePath = [document.basePathOfDocument lastPathComponent];
+			subpath = [includePath stringByAppendingPathComponent:subpath];
+		}
 
 		// Prepare relative path from output path to the document now.
 		basePath = [self.htmlStaticDocumentsSubpath stringByAppendingPathComponent:subpath];
@@ -331,12 +427,13 @@ - (NSString *)outputPathForObject:(id)object withExtension:(NSString *)extension
 }
 
 - (NSString *)htmlRelativePathToIndexFromObject:(id)object {
-	// Returns relative path prefix from the given source to the given destination or empty string if both objects live in the same path. This is pretty simple except when either object is a document. In such case we need to handle arbitrary depth.	
+	// Returns relative path prefix from the given source to the given destination or empty string if both objects live in the same path. This is pretty simple except when object is a document. In such case we need to handle arbitrary depth.	
 	if ([object isStaticDocument]) {
-		NSString *subpath = [[object subpathOfDocument] stringByDeletingLastPathComponent];
+		NSString *subpath = [self outputPathForObject:object withExtension:@"extension"];
+		subpath = [subpath stringByDeletingLastPathComponent];
 		if ([subpath length] > 0) {
 			NSArray *components = [subpath pathComponents];
-			NSMutableString *result = [NSMutableString stringWithString:@"../"];
+			NSMutableString *result = [NSMutableString stringWithCapacity:[subpath length]];
 			for (NSUInteger i=0; i<[components count]; i++) [result appendString:@"../"];
 			return result;
 		}
@@ -445,6 +542,9 @@ - (NSString *)versionIdentifier {
 @synthesize keepMergedCategoriesSections;
 @synthesize prefixMergedCategoriesSectionsWithCategoryName;
 
+@synthesize prefixLocalMembersInRelatedItemsList;
+@synthesize embedCrossReferencesWhenProcessingMarkdown;
+
 @synthesize createHTML;
 @synthesize createDocSet;
 @synthesize installDocSet;

Application/GBApplicationStringsProvider.m

@@ -136,8 +136,8 @@ - (NSDictionary *)appledocData {
 	if (!result) {
 		result = [[NSMutableDictionary alloc] init];
 		[result setObject:@"appledoc" forKey:@"tool"];
-		[result setObject:@"2.0.2" forKey:@"version"];
-		[result setObject:@"566" forKey:@"build"];
+		[result setObject:@"2.0.3" forKey:@"version"];
+		[result setObject:@"632" forKey:@"build"];
 		[result setObject:@"http://appledoc.gentlebytes.com" forKey:@"homepage"];
 	}
 	return result;