Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Refined exit codes handling. Closes #102.

This commit concentrates on two related issues:

- It adds a new command line switch `--exit-threshold` which allows users specify the threshold value (numeric) which is used to filter out tool exit codes: if reported exit code is below the threshold value, tool simply returns 0.

- Restructures exit codes values to have higher value representing more severe condition. This plays nicer with previous point. Currently warning has value 1, error 2, fatal 3 (although fatal is not used currently in the tool).

Note that it's not possible to suppress crashes, regardless of whether the threshold is set above the value (250 currently)!

Also updated build number to 692.
  • Loading branch information...
commit ee933859741a49c31a1321fea355de14649ca797 1 parent e12cab2
tomaz tomaz authored
2  AppledocTests-Info.plist
View
@@ -17,6 +17,6 @@
<key>CFBundleSignature</key>
<string>????</string>
<key>CFBundleVersion</key>
- <string>687</string>
+ <string>692</string>
</dict>
</plist>
1  AppledocTests_prefix.pch
View
@@ -15,6 +15,7 @@
#import "NSError+GBError.h"
#import "NSFileManager+GBFileManager.h"
#import "GBLog.h"
+ #import "GBExitCodes.h"
#define HC_SHORTHAND
#import <GHUnit/GHUnit.h>
10 Application/GBAppledocApplication.m
View
@@ -36,6 +36,7 @@
static NSString *kGBArgInstallDocSet = @"install-docset";
static NSString *kGBArgPublishDocSet = @"publish-docset";
static NSString *kGBArgKeepIntermediateFiles = @"keep-intermediate-files";
+static NSString *kGBArgExitCodeThreshold = @"exit-threshold";
static NSString *kGBArgRepeatFirstParagraph = @"repeat-first-par";
static NSString *kGBArgKeepUndocumentedObjects = @"keep-undocumented-objects";
@@ -209,8 +210,9 @@ - (int)application:(DDCliApplication *)app runWithArguments:(NSArray *)arguments
return GBEXIT_ASSERT_GENERIC;
}
- GBLogDebug(@"Exiting with result %ld...", kGBLogBasedResult);
- return kGBLogBasedResult;
+ int result = (kGBLogBasedResult >= self.settings.exitCodeThreshold) ? kGBLogBasedResult : 0;
+ GBLogDebug(@"Exiting with result %ld (reported result was %ld)...", result, kGBLogBasedResult);
+ return result;
}
- (void)application:(DDCliApplication *)app willParseOptions:(DDGetoptLongParser *)optionParser {
@@ -269,6 +271,7 @@ - (void)application:(DDCliApplication *)app willParseOptions:(DDGetoptLongParser
{ kGBArgMergeCategoriesToClasses, 0, DDGetoptNoArgument },
{ kGBArgKeepMergedCategoriesSections, 0, DDGetoptNoArgument },
{ kGBArgPrefixMergedCategoriesSectionsWithCategoryName, 0, DDGetoptNoArgument },
+ { kGBArgExitCodeThreshold, 0, DDGetoptRequiredArgument },
{ GBNoArg(kGBArgKeepIntermediateFiles), 0, DDGetoptNoArgument },
{ GBNoArg(kGBArgKeepUndocumentedObjects), 0, DDGetoptNoArgument },
{ GBNoArg(kGBArgKeepUndocumentedMembers), 0, DDGetoptNoArgument },
@@ -650,6 +653,7 @@ - (void)setCrossrefFormat:(NSString *)value { self.settings.commentComponents.cr
- (void)setExplicitCrossref:(BOOL)value { self.settings.commentComponents.crossReferenceMarkersTemplate = value ? @"<%@>" : @"<?%@>?"; }
- (void)setNoExplicitCrossref:(BOOL)value { [self setExplicitCrossref:!value]; }
+- (void)setExitThreshold:(int)value { self.settings.exitCodeThreshold = value; }
- (void)setKeepIntermediateFiles:(BOOL)value { self.settings.keepIntermediateFiles = value;}
- (void)setKeepUndocumentedObjects:(BOOL)value { self.settings.keepUndocumentedObjects = value; }
- (void)setKeepUndocumentedMembers:(BOOL)value { self.settings.keepUndocumentedMembers = value; }
@@ -778,6 +782,7 @@ - (void)printSettingsAndArguments:(NSArray *)arguments {
ddprintf(@"--%@ = %@\n", kGBArgKeepMergedCategoriesSections, PRINT_BOOL(self.settings.keepMergedCategoriesSections));
ddprintf(@"--%@ = %@\n", kGBArgPrefixMergedCategoriesSectionsWithCategoryName, PRINT_BOOL(self.settings.prefixMergedCategoriesSectionsWithCategoryName));
ddprintf(@"--%@ = %@\n", kGBArgCrossRefFormat, self.settings.commentComponents.crossReferenceMarkersTemplate);
+ ddprintf(@"--%@ = %ld\n", kGBArgExitCodeThreshold, self.settings.exitCodeThreshold);
ddprintf(@"\n");
ddprintf(@"--%@ = %@\n", kGBArgWarnOnMissingOutputPath, PRINT_BOOL(self.settings.warnOnMissingOutputPathArgument));
@@ -840,6 +845,7 @@ - (void)printHelp {
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");
+ PRINT_USAGE(@" ", kGBArgExitCodeThreshold, @"<number>", @"Exit code threshold below which 0 is returned");
ddprintf(@"\n");
ddprintf(@"WARNINGS\n");
PRINT_USAGE(@" ", kGBArgWarnOnMissingOutputPath, @"", @"[b] Warn if output path is not given");
12 Application/GBApplicationSettingsProvider.h
View
@@ -28,7 +28,7 @@ extern id kGBCustomDocumentIndexDescKey;
1. Create a new global string as `static NSString` containing the command line switch name.
2. Register the switch to `DDCli` (add negated switch if it's a boolean).
- 3. Add unit test in `GBAppledocApplicationTesting.m` that validates the switch is properly mapped to setting property (note that boolean switches require testing normal and negated variants!).
+ 3. Add unit test in `GBApplicationTesting.m` that validates the switch is properly mapped to setting property (note that boolean switches require testing normal and negated variants!).
4. Add KVC setter and map to corresponding property to make the test pass (again booleans require two setters).
5. If the switch value uses template placeholders, add unit test in `GBApplicationSettingsProviderTesting.m` that validates the switch is handled.
6. If previous point was used, add the code to `replaceAllOccurencesOfPlaceholderStringsInSettingsValues` to make the test pass.
@@ -220,6 +220,16 @@ 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.
2  Application/GBApplicationSettingsProvider.m
View
@@ -82,6 +82,7 @@ - (id)init {
self.keepUndocumentedObjects = NO;
self.keepUndocumentedMembers = NO;
self.findUndocumentedMembersDocumentation = YES;
+ self.exitCodeThreshold = 0;
self.mergeCategoriesToClasses = YES;
self.keepMergedCategoriesSections = NO;
@@ -594,6 +595,7 @@ - (NSString *)versionIdentifier {
@synthesize publishDocSet;
@synthesize keepIntermediateFiles;
@synthesize cleanupOutputPathBeforeRunning;
+@synthesize exitCodeThreshold;
@synthesize warnOnMissingOutputPathArgument;
@synthesize warnOnMissingCompanyIdentifier;
2  Application/GBApplicationStringsProvider.m
View
@@ -138,7 +138,7 @@ - (NSDictionary *)appledocData {
result = [[NSMutableDictionary alloc] init];
[result setObject:@"appledoc" forKey:@"tool"];
[result setObject:@"2.0.3" forKey:@"version"];
- [result setObject:@"687" forKey:@"build"];
+ [result setObject:@"692" forKey:@"build"];
[result setObject:@"http://appledoc.gentlebytes.com" forKey:@"homepage"];
}
return result;
4 Common/GBExitCodes.h
View
@@ -11,8 +11,8 @@
#pragma mark - Exit code "domains"
-#define GBEXIT_DOMAIN_ASSERT 10
-#define GBEXIT_DOMAIN_LOG 20
+#define GBEXIT_DOMAIN_LOG 1
+#define GBEXIT_DOMAIN_ASSERT 250
#pragma mark - Internal inconsistencies codes
7 Testing/GBApplicationTesting.m
View
@@ -300,6 +300,13 @@ - (void)testCrossRefFormat_shouldAssignValueToSettings {
assertThat(settings.commentComponents.crossReferenceMarkersTemplate, is(@"FORMAT"));
}
+- (void)testExitCodeThreshold_shouldAssignValueToSettings {
+ // setup & execute
+ GBApplicationSettingsProvider *settings = [self settingsByRunningWithArgs:@"--exit-threshold", @"2", nil];
+ // verify
+ assertThatInteger(settings.exitCodeThreshold, equalToInteger(2));
+}
+
#pragma mark Warnings settings testing
- (void)testWarnOnMissingOutputPath_shouldAssignValueToSettings {
2  appledoc.xcodeproj/project.pbxproj
View
@@ -92,6 +92,7 @@
7340F02811FCC63100E712A4 /* NSFileManager+GBFileManager.m in Sources */ = {isa = PBXBuildFile; fileRef = 7340F02511FCC63100E712A4 /* NSFileManager+GBFileManager.m */; };
7340F02911FCC63100E712A4 /* NSObject+GBObject.m in Sources */ = {isa = PBXBuildFile; fileRef = 7340F02711FCC63100E712A4 /* NSObject+GBObject.m */; };
73473D3112A38B730011336C /* GBHTMLOutputGenerator.m in Sources */ = {isa = PBXBuildFile; fileRef = 73473D3012A38B730011336C /* GBHTMLOutputGenerator.m */; };
+ 735259D713793ED7003F0D09 /* GBExitCodes.m in Sources */ = {isa = PBXBuildFile; fileRef = 73C4C8601377DFF70024FA77 /* GBExitCodes.m */; };
7355E12E1312736D00B9C000 /* libmarkdown.a in Frameworks */ = {isa = PBXBuildFile; fileRef = 7355E12D1312736D00B9C000 /* libmarkdown.a */; };
7355E12F1312736D00B9C000 /* libmarkdown.a in Frameworks */ = {isa = PBXBuildFile; fileRef = 7355E12D1312736D00B9C000 /* libmarkdown.a */; };
7359B149129A5A0700F67AD1 /* GRBoolean.m in Sources */ = {isa = PBXBuildFile; fileRef = 7359B120129A5A0600F67AD1 /* GRBoolean.m */; };
@@ -1235,6 +1236,7 @@
7359B16C129A5A0700F67AD1 /* GRMustacheVersion.m in Sources */,
73F568C012A22A7900A72BB2 /* DDASLLogger.m in Sources */,
73F568C212A22A7900A72BB2 /* DDFileLogger.m in Sources */,
+ 735259D713793ED7003F0D09 /* GBExitCodes.m in Sources */,
73F568C412A22A7900A72BB2 /* DDLog.m in Sources */,
73F568C612A22A7900A72BB2 /* DDTTYLogger.m in Sources */,
739C0C4712AC258B00F0130B /* GBProcessor-UndocumentedObjectsTesting.m in Sources */,
Please sign in to comment.
Something went wrong with that request. Please try again.