Browse files

Implemented message file generation when installing documentation set.

…Closes #71.

The problem was that users expected some files on the `--output` path, however appledoc by default moves files from previous generation phase to next one. So if `--install-docset` is used, output path becomes empty. Although this can be regulated by `--keep-intermediate-files` option, it's confusing as it's off by default.

I chose an user's suggestion to create a text file in output path in such case. To make it even more useful, the file contains the path the documentation set was installed to and installation time.

To make it even less confusing, contents of output path are deleted before running appledoc. Note that although this can be suppressed by an application settings, the setting itself is not wired to a command line switch; having the setting already implemented would make implementing switch later on simpler.
  • Loading branch information...
tomaz committed Feb 27, 2011
1 parent 03972ce commit 1edaeab19686f316e5228c13ce6d74e68bf1de54
@@ -87,6 +87,7 @@
@interface GBAppledocApplication ()
- (void)initializeLoggingSystem;
+- (void)deleteContentsOfOutputPath;
- (void)validateSettingsAndArguments:(NSArray *)arguments;
- (NSString *)standardizeCurrentDirectoryForPath:(NSString *)path;
- (NSString *)combineBasePath:(NSString *)base withRelativePath:(NSString *)path;
@@ -165,6 +166,7 @@ - (int)application:(DDCliApplication *)app runWithArguments:(NSArray *)arguments
@try {
[self initializeLoggingSystem];
+ [self deleteContentsOfOutputPath];
GBStore *store = [[GBStore alloc] init];
@@ -309,6 +311,30 @@ - (void)initializeLoggingSystem {
[formatter release];
+- (void)deleteContentsOfOutputPath {
+ // Removes all files from output path to have a clean start. Although this is not necessary from functionality point of view, it makes the tool less confusing as output only contains files generated by this run. This is sent after initializing logging system, so we can use logging. Note that in case cleanup fails, we simply warn and continue; it the rest of the steps succeed, we can leave everything.
+ if (!self.settings.cleanupOutputPathBeforeRunning) return;
+ NSString *outputPath = self.settings.outputPath;
+ NSString *standardizedOutput = [outputPath stringByStandardizingPath];
+ NSError *error = nil;
+ GBLogInfo(@"Deleting contents of output path '%@'...", outputPath);
+ NSArray *contents = [self.fileManager contentsOfDirectoryAtPath:standardizedOutput error:&error];
+ if (error) {
+ GBLogNSError(error, @"Failed enumerating contents of output path '%@'!, for cleaning up!", outputPath);
+ return;
+ }
+ for (NSString *subpath in contents) {
+ GBLogDebug(@"- Deleting '%@'...", subpath);
+ NSString *filename = [standardizedOutput stringByAppendingPathComponent:subpath];
+ if (![self.fileManager removeItemAtPath:filename error:&error] && error) {
+ GBLogNSError(error, @"Failed removing '%@' while cleaning up output!", filename);
+ }
+ }
- (void)validateSettingsAndArguments:(NSArray *)arguments {
// Validate we have valid templates path - we use the value of the templatesFound set within initializeGlobalSettingsAndValidateTemplates. We can't simply raise exception there because that message is sent before handling help or version; so we would be required to provide valid templates path even if we just wanted "appledoc --help". As this message is sent afterwards, we can raise exception here. Not as elegant, but needed.
if (!self.templatesFound) {
@@ -193,9 +193,19 @@
/** 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!
+ @see cleanupOutputPathBeforeRunning
@property (assign) BOOL keepIntermediateFiles;
+/** Specifies whether contents of output path should be deleted befor running the tool.
+ This is useful to have output path only contain files generated by latest run instead of keeping previous files. Although appledoc removes existing files when needed, it leaves any file or directory that's not touched by this run. So if we created docset in previous run, and only html in current one, the output would contain both subdirs - the fresh HTML files and documentation set from the previous run. Using this option cleans up output path before running so we can start fresh and prevent confusion.
+ @see keepIntermediateFiles
+ */
+@property (assign) BOOL cleanupOutputPathBeforeRunning;
/** 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.
@@ -74,6 +74,7 @@ - (id)init {
self.publishDocSet = NO;
self.repeatFirstParagraphForMemberDescription = YES;
self.keepIntermediateFiles = NO;
+ self.cleanupOutputPathBeforeRunning = YES;
self.keepUndocumentedObjects = NO;
self.keepUndocumentedMembers = NO;
self.findUndocumentedMembersDocumentation = YES;
@@ -550,6 +551,7 @@ - (NSString *)versionIdentifier {
@synthesize installDocSet;
@synthesize publishDocSet;
@synthesize keepIntermediateFiles;
+@synthesize cleanupOutputPathBeforeRunning;
@synthesize warnOnMissingOutputPathArgument;
@synthesize warnOnMissingCompanyIdentifier;
@@ -11,6 +11,12 @@
#import "GBTask.h"
#import "GBDocSetInstallGenerator.h"
+@interface GBDocSetInstallGenerator ()
+- (void)touchInstallMessageFile;
+#pragma mark -
@implementation GBDocSetInstallGenerator
#pragma Generation handling
@@ -39,6 +45,9 @@ - (BOOL)generateOutputWithStore:(id)store error:(NSError **)error {
return NO;
+ // Prepare text file with message on the output path to avoid confusion when empty path is found.
+ [self touchInstallMessageFile];
// Prepare AppleScript for loading the documentation into the Xcode.
GBLogVerbose(@"Installing DocSet to Xcode...");
NSMutableString* installScript = [NSMutableString string];
@@ -58,6 +67,18 @@ - (BOOL)generateOutputWithStore:(id)store error:(NSError **)error {
return YES;
+- (void)touchInstallMessageFile {
+ // Creates or updates install message file at output path.
+ NSString *filename = [self.settings.outputPath stringByAppendingPathComponent:@"docset-installed.txt"];
+ NSMutableString *message = [NSMutableString string];
+ [message appendString:@"Documentation set was installed to Xcode!\n\n"];
+ [message appendFormat:@"Path: %@\n", self.outputUserPath];
+ [message appendFormat:@"Time: %@", [NSDate date]];
+ NSError *error = nil;
+ [message writeToFile:[filename stringByStandardizingPath] atomically:NO encoding:NSUTF8StringEncoding error:&error];
+ if (error) GBLogNSError(error, @"Failed writting docset installed message file at '%@'!", filename);
#pragma mark Overriden methods
- (NSString *)outputUserPath {

0 comments on commit 1edaeab

Please sign in to comment.