Implemented optional required escaping for cross references. Closes #8.

The issue was that user had no way of being explicit about which word should be considered cross reference and which not. Result was that any word that was also valid cross reference was converted to one. This lead to unexpected references being created from normal words - like "paragraphs" and similar.

The user now has two choices regarding cross references: power users can provide their own cross references markers template regex, while simpler choice is to turn on explicit cross references detection. Actually this sets default markers template under the hood, so the two options should not be used together.

Application/GBAppledocApplication.m

@@ -41,6 +41,9 @@
 static NSString *kGBArgKeepMergedCategoriesSections = @"keep-merged-sections";
 static NSString *kGBArgPrefixMergedCategoriesSectionsWithCategoryName = @"prefix-merged-sections";
 
+static NSString *kGBArgExplicitCrossRef = @"explicit-crossref";
+static NSString *kGBArgCrossRefFormat = @"crossref-format";
+
 static NSString *kGBArgWarnOnMissingOutputPath = @"warn-missing-output-path";
 static NSString *kGBArgWarnOnMissingCompanyIdentifier = @"warn-missing-company-id";
 static NSString *kGBArgWarnOnUndocumentedObject = @"warn-undocumented-object";
@@ -226,6 +229,10 @@ - (void)application:(DDCliApplication *)app willParseOptions:(DDGetoptLongParser
 		{ GBNoArg(kGBArgInstallDocSet),										0,		DDGetoptNoArgument },
 		{ GBNoArg(kGBArgPublishDocSet),										0,		DDGetoptNoArgument },
 
+		{ kGBArgCrossRefFormat,												0,		DDGetoptRequiredArgument },
+		{ kGBArgExplicitCrossRef,											0,		DDGetoptNoArgument },
+		{ GBNoArg(kGBArgExplicitCrossRef),									0,		DDGetoptNoArgument },
+
 		{ kGBArgKeepIntermediateFiles,										0,		DDGetoptNoArgument },
 		{ kGBArgKeepUndocumentedObjects,									0,		DDGetoptNoArgument },
 		{ kGBArgKeepUndocumentedMembers,									0,		DDGetoptNoArgument },
@@ -460,6 +467,10 @@ - (void)setNoCreateDocset:(BOOL)value { self.settings.createDocSet = !value; }
 - (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)setKeepIntermediateFiles:(BOOL)value { self.settings.keepIntermediateFiles = value;}
 - (void)setKeepUndocumentedObjects:(BOOL)value { self.settings.keepUndocumentedObjects = value; }
 - (void)setKeepUndocumentedMembers:(BOOL)value { self.settings.keepUndocumentedMembers = value; }
@@ -582,6 +593,7 @@ - (void)printSettingsAndArguments:(NSArray *)arguments {
 	ddprintf(@"--%@ = %@\n", kGBArgMergeCategoriesToClasses, PRINT_BOOL(self.settings.mergeCategoriesToClasses));
 	ddprintf(@"--%@ = %@\n", kGBArgKeepMergedCategoriesSections, PRINT_BOOL(self.settings.keepMergedCategoriesSections));
 	ddprintf(@"--%@ = %@\n", kGBArgPrefixMergedCategoriesSectionsWithCategoryName, PRINT_BOOL(self.settings.prefixMergedCategoriesSectionsWithCategoryName));
+	ddprintf(@"--%@ = %@\n", kGBArgCrossRefFormat, self.settings.commentComponents.crossReferenceMarkersTemplate);
 	ddprintf(@"\n");
 
 	ddprintf(@"--%@ = %@\n", kGBArgWarnOnMissingOutputPath, PRINT_BOOL(self.settings.warnOnMissingOutputPathArgument));
@@ -639,6 +651,8 @@ - (void)printHelp {
 	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");
+	PRINT_USAGE(@"   ", kGBArgExplicitCrossRef, @"", @"[b] Shortcut for explicit default cross ref template");
+	PRINT_USAGE(@"   ", kGBArgCrossRefFormat, @"<string>", @"Cross reference template regex");
 	ddprintf(@"\n");
 	ddprintf(@"WARNINGS\n");
 	PRINT_USAGE(@"   ", kGBArgWarnOnMissingOutputPath, @"", @"[b] Warn if output path is not given");
@@ -715,4 +729,3 @@ - (void)printHelpForShortOption:(NSString *)aShort longOption:(NSString *)aLong
 }
 
 @end
-

Application/GBCommentComponentsProvider.h

@@ -96,20 +96,50 @@
 /// @name Cross references definitions
 ///---------------------------------------------------------------------------------------
 
-/** Returns the regex used for matching (possible) remote member cross references with capture 1 containing object name and capture 2 member name. */
-@property (readonly) NSString *remoteMemberCrossReferenceRegex;
+/** Returns the regex used for matching (possible) remote member cross references with capture 1 containing object name and capture 2 member name. 
+ 
+ The result of the method depends on the templated value: if the value is `YES`, the string includes template from `crossReferenceMarkersTemplate`, otherwise it only contains "pure" regex. The first option should be used for in-text cross references detection, while the second for `crossReferenceRegex` matching.
+ 
+ @param templates If `YES` templated regex is returned, otherwise pure one.
+ @return Returns the regex used for matching cross reference.
+ */
+- (NSString *)remoteMemberCrossReferenceRegex:(BOOL)templated;
 
-/** Returns the regex used for matching (possible) local member cross reference with capture 1 containing member name. */
-@property (readonly) NSString *localMemberCrossReferenceRegex;
+/** Returns the regex used for matching (possible) local member cross reference with capture 1 containing member name.
+ 
+ The result of the method depends on the templated value: if the value is `YES`, the string includes template from `crossReferenceMarkersTemplate`, otherwise it only contains "pure" regex. The first option should be used for in-text cross references detection, while the second for `crossReferenceRegex` matching.
+ 
+ @param templates If `YES` templated regex is returned, otherwise pure one.
+ @return Returns the regex used for matching cross reference.
+ */
+- (NSString *)localMemberCrossReferenceRegex:(BOOL)templated;
 
-/** Returns the regex used for matching (possible) category cross reference with capture 1 containing category name. */
-@property (readonly) NSString *categoryCrossReferenceRegex;
+/** Returns the regex used for matching (possible) category cross reference with capture 1 containing category name.
+ 
+ The result of the method depends on the templated value: if the value is `YES`, the string includes template from `crossReferenceMarkersTemplate`, otherwise it only contains "pure" regex. The first option should be used for in-text cross references detection, while the second for `crossReferenceRegex` matching.
+ 
+ @param templates If `YES` templated regex is returned, otherwise pure one.
+ @return Returns the regex used for matching cross reference.
+ */
+- (NSString *)categoryCrossReferenceRegex:(BOOL)templated;
 
-/** Returns the regex used for matching (possible) class or protocol cross reference with capture 1 containing object name. */
-@property (readonly) NSString *objectCrossReferenceRegex;
+/** Returns the regex used for matching (possible) class or protocol cross reference with capture 1 containing object name.
+ 
+ The result of the method depends on the templated value: if the value is `YES`, the string includes template from `crossReferenceMarkersTemplate`, otherwise it only contains "pure" regex. The first option should be used for in-text cross references detection, while the second for `crossReferenceRegex` matching.
+ 
+ @param templates If `YES` templated regex is returned, otherwise pure one.
+ @return Returns the regex used for matching cross reference.
+ */
+- (NSString *)objectCrossReferenceRegex:(BOOL)templated;
 
-/** Returns the regex used for matching URL cross reference with caption 1 contining the URL itself. */
-@property (readonly) NSString *urlCrossReferenceRegex;
+/** Returns the regex used for matching URL cross reference with caption 1 contining the URL itself.
+ 
+ The result of the method depends on the templated value: if the value is `YES`, the string includes template from `crossReferenceMarkersTemplate`, otherwise it only contains "pure" regex. The first option should be used for in-text cross references detection, while the second for `crossReferenceRegex` matching.
+ 
+ @param templates If `YES` templated regex is returned, otherwise pure one.
+ @return Returns the regex used for matching cross reference.
+ */
+- (NSString *)urlCrossReferenceRegex:(BOOL)templated;
 
 ///---------------------------------------------------------------------------------------
 /// @name Common definitions

Application/GBCommentComponentsProvider.m

@@ -103,25 +103,45 @@ - (NSString *)crossReferenceRegex {
 
 #pragma mark Cross references detection
 
-- (NSString *)remoteMemberCrossReferenceRegex {
+- (NSString *)remoteMemberCrossReferenceRegex:(BOOL)templated {
 	// +[Class member] or -[Class member] or simply [Class member].
-	GBRETURN_ON_DEMAND([self crossReferenceRegexForRegex:@"[+-]?\\[(\\S+)\\s+(\\S+)\\]"]);
+	if (templated) {
+		GBRETURN_ON_DEMAND([self crossReferenceRegexForRegex:[self remoteMemberCrossReferenceRegex:NO]]);
+	} else {
+		GBRETURN_ON_DEMAND(@"[+-]?\\[(\\S+)\\s+(\\S+)\\]");
+	}
 }
 
-- (NSString *)localMemberCrossReferenceRegex {
-	GBRETURN_ON_DEMAND([self crossReferenceRegexForRegex:@"([^>,.;!?()\\s]+)"]);
+- (NSString *)localMemberCrossReferenceRegex:(BOOL)templated {
+	if (templated) {
+		GBRETURN_ON_DEMAND([self crossReferenceRegexForRegex:[self localMemberCrossReferenceRegex:NO]]);
+	} else {
+		GBRETURN_ON_DEMAND(@"([^>,.;!?()\\s]+)");
+	}
 }
 
-- (NSString *)categoryCrossReferenceRegex {
-	GBRETURN_ON_DEMAND([self crossReferenceRegexForRegex:@"([^(][^>,.:;!?)\\s]+\\))"]);
+- (NSString *)categoryCrossReferenceRegex:(BOOL)templated {
+	if (templated) {
+		GBRETURN_ON_DEMAND([self crossReferenceRegexForRegex:[self categoryCrossReferenceRegex:NO]]);
+	} else {
+		GBRETURN_ON_DEMAND(@"([^(][^>,.:;!?)\\s]+\\))");
+	}
 }
 
-- (NSString *)objectCrossReferenceRegex {
-	GBRETURN_ON_DEMAND([self crossReferenceRegexForRegex:@"([^>,.:;!?()\\s]+)"]);
+- (NSString *)objectCrossReferenceRegex:(BOOL)templated {
+	if (templated) {
+		GBRETURN_ON_DEMAND([self crossReferenceRegexForRegex:[self objectCrossReferenceRegex:NO]]);
+	} else {
+		GBRETURN_ON_DEMAND(@"([^>,.:;!?()\\s]+)");
+	}
 }
 
-- (NSString *)urlCrossReferenceRegex {
-	GBRETURN_ON_DEMAND([self crossReferenceRegexForRegex:@"(\\b(?:mailto\\:|(?:https?|ftps?|news|rss|file)\\://)[a-zA-Z0-9@:\\-.]+(?::(\\d+))?(?:(?:/[a-zA-Z0-9\\-._?,'+\\&%$=~*!():@\\\\]*)+)?)"]);
+- (NSString *)urlCrossReferenceRegex:(BOOL)templated {
+	if (templated) {
+		GBRETURN_ON_DEMAND([self crossReferenceRegexForRegex:[self urlCrossReferenceRegex:NO]]);
+	} else {
+		GBRETURN_ON_DEMAND(@"(\\b(?:mailto\\:|(?:https?|ftps?|news|rss|file)\\://)[a-zA-Z0-9@:\\-.]+(?::(\\d+))?(?:(?:/[a-zA-Z0-9\\-._?,'+\\&%$=~*!():@\\\\]*)+)?)");
+	}
 }
 
 #pragma mark Common detection