Browse files

Addressing `&` and `&token;` issues when indexing documentation set, …

…partially easing #107.

Note: unfortunately it wasn't possible to continue indexing remaining files after encountering an error - docsetutil takes path to docset bundle, not individual files. So all symbols in the offending file AND all symbols in subsequent files will not be indexed.

Also note that appledoc will log a warning and hence exit with code 1 in case it gets these errors! You'll probably want to use `--exit-threshold 2` or more if you're running from Xcode build script.

For the moment, the only "workaround" is to stay clear of using these symbols in your own documentation. If you're using third party libraries or frameworks containing these symbols and only running them through appledoc to get similar looking docs encountering issues, you can only pass it through `--create-html` phase. If you want to have it integrated in Xcode, then go ahead and experiment to see how much of it is usable...
  • Loading branch information...
1 parent f26d132 commit 32ff9963c38384311d06ceb1259b1e14e6abdc43 @tomaz committed Jun 9, 2011
View
2 AppledocTests-Info.plist
@@ -17,6 +17,6 @@
<key>CFBundleSignature</key>
<string>????</string>
<key>CFBundleVersion</key>
- <string>701</string>
+ <string>702</string>
</dict>
</plist>
View
26 Application/GBApplicationSettingsProvider.h
@@ -220,16 +220,6 @@ extern id kGBCustomDocumentIndexDescKey;
*/
@property (assign) BOOL cleanupOutputPathBeforeRunning;
-/** Species the threshold below which exit codes are truncated to zero.
-
- This affects the reported exit code when ending a run session. It allows users preventing reporting certain types of exit codes, based on the given threshold. If the reported exit code is lower than the given threshold, zero is returned instead. If the reported exit code is equal or greater than the threshold, it is returned as the result of the tool.
-
- This is useful to prevent higher level tools invoking appledoc (Xcode for example) treating reported warnings as invalid run for example. By default, this value is zero, so no exit code is suppressed.
-
- @warning *Note:* Generally appledoc uses higher exit codes for more severe issues, so the greater the threshold, the more "permissive" the exit code will be, regardless of what happens inside the tool. However, crashes are always reported with proper exit codes, regardless of threshold value! Also note that the threshold value relies on the implementation of the exit codes #define values!
- */
-@property (assign) int exitCodeThreshold;
-
/** Indicates whether the first paragraph needs to be repeated within method and property description or not.
If `YES`, first paragraph is repeated in members description, otherwise not.
@@ -318,6 +308,22 @@ extern id kGBCustomDocumentIndexDescKey;
*/
@property (assign) BOOL prefixLocalMembersInRelatedItemsList;
+/** Specifies whether we should treat docsetutil indexing errors as fatals or not.
+
+ Turning this to `YES` will cause docsetutil indexing error failing build, otherwise it will continue with remaining files. The main reason for implementing this is to allow handling uncompatible descriptions as graceful as possible.
+ */
+@property (assign) BOOL treatDocSetIndexingErrorsAsFatals;
+
+/** Species the threshold below which exit codes are truncated to zero.
+
+ This affects the reported exit code when ending a run session. It allows users preventing reporting certain types of exit codes, based on the given threshold. If the reported exit code is lower than the given threshold, zero is returned instead. If the reported exit code is equal or greater than the threshold, it is returned as the result of the tool.
+
+ This is useful to prevent higher level tools invoking appledoc (Xcode for example) treating reported warnings as invalid run for example. By default, this value is zero, so no exit code is suppressed.
+
+ @warning *Note:* Generally appledoc uses higher exit codes for more severe issues, so the greater the threshold, the more "permissive" the exit code will be, regardless of what happens inside the tool. However, crashes are always reported with proper exit codes, regardless of threshold value! Also note that the threshold value relies on the implementation of the exit codes #define values!
+ */
+@property (assign) int exitCodeThreshold;
+
///---------------------------------------------------------------------------------------
/// @name Warnings handling
///---------------------------------------------------------------------------------------
View
2 Application/GBApplicationSettingsProvider.m
@@ -82,6 +82,7 @@ - (id)init {
self.keepUndocumentedObjects = NO;
self.keepUndocumentedMembers = NO;
self.findUndocumentedMembersDocumentation = YES;
+ self.treatDocSetIndexingErrorsAsFatals = NO;
self.exitCodeThreshold = 0;
self.mergeCategoriesToClasses = YES;
@@ -599,6 +600,7 @@ - (NSString *)versionIdentifier {
@synthesize publishDocSet;
@synthesize keepIntermediateFiles;
@synthesize cleanupOutputPathBeforeRunning;
+@synthesize treatDocSetIndexingErrorsAsFatals;
@synthesize exitCodeThreshold;
@synthesize warnOnMissingOutputPathArgument;
View
2 Application/GBApplicationStringsProvider.m
@@ -138,7 +138,7 @@ - (NSDictionary *)appledocData {
result = [[NSMutableDictionary alloc] init];
[result setObject:@"appledoc" forKey:@"tool"];
[result setObject:@"2.0.4" forKey:@"version"];
- [result setObject:@"701" forKey:@"build"];
+ [result setObject:@"702" forKey:@"build"];
[result setObject:@"http://appledoc.gentlebytes.com" forKey:@"homepage"];
}
return result;
View
8 Generating/GBDocSetOutputGenerator.m
@@ -182,8 +182,12 @@ - (BOOL)indexDocSet:(NSError **)error {
if (error) GBLogError(@"!> %@", [error stringByTrimmingWhitespaceAndNewLine]);
}];
if (!result) {
- if (error) *error = [NSError errorWithCode:GBErrorDocSetUtilIndexingFailed description:@"docsetutil failed to index the documentation set!" reason:task.lastStandardError];
- return NO;
+ if (self.settings.treatDocSetIndexingErrorsAsFatals) {
+ if (error) *error = [NSError errorWithCode:GBErrorDocSetUtilIndexingFailed description:@"docsetutil failed to index the documentation set!" reason:task.lastStandardError];
+ return NO;
+ } else {
+ GBLogWarn(@"docsetutil failed to index the documentation set, continuing with what was indexed...");
+ }
}
return YES;
}

0 comments on commit 32ff996

Please sign in to comment.