Permalink
Browse files

Refactored output generation by moving all specifics to OutputGenerat…

…or subclasses.

Each concrete output generator is implemented as a subclass of OutputGenerator instead of extending DoxygenConverter by another category. This results in much cleaner class structure and responsibility division as well as much more decoupling between different output generation objects.
  • Loading branch information...
1 parent 8b9c738 commit 3a46c43e8e138bdb5bc78b0e344cfd29f977fb48 @tomaz committed Jun 12, 2009
Showing with 2,016 additions and 1,606 deletions.
  1. +12 −0 CommandLineParser.h
  2. +9 −0 CommandLineParser.m
  3. +43 −0 Constants.h
  4. +60 −0 Constants.m
  5. +40 −15 DoxygenConverter+DocSet.h → DocSetOutputGenerator.h
  6. +64 −16 DoxygenConverter+DocSet.m → DocSetOutputGenerator.m
  7. +0 −38 DoxygenConverter+CleanOutput.h
  8. +0 −74 DoxygenConverter+CleanOutput.m
  9. +0 −65 DoxygenConverter+Helpers.h
  10. +0 −40 DoxygenConverter+Helpers.m
  11. +9 −48 DoxygenConverter.h
  12. +56 −109 DoxygenConverter.m
  13. +28 −20 DoxygenConverter+Doxygen.h → DoxygenOutputGenerator.h
  14. +33 −7 DoxygenConverter+Doxygen.m → DoxygenOutputGenerator.m
  15. +130 −267 OutputGenerator.h
  16. +69 −557 OutputGenerator.m
  17. +68 −0 OutputInfoProvider.h
  18. +46 −0 OutputProcessing.h
  19. +67 −0 Systemator.h
  20. +64 −1 Systemator.m
  21. +4 −36 XHTMLOutputGenerator.h
  22. +51 −44 XHTMLOutputGenerator.m
  23. +4 −15 OutputGenerator+GeneralParsingAPI.h → XMLBasedOutputGenerator+GeneralParsingAPI.h
  24. +3 −11 OutputGenerator+GeneralParsingAPI.m → XMLBasedOutputGenerator+GeneralParsingAPI.m
  25. +4 −4 OutputGenerator+HierarchyParsingAPI.h → XMLBasedOutputGenerator+HierarchyParsingAPI.h
  26. +4 −4 OutputGenerator+HierarchyParsingAPI.m → XMLBasedOutputGenerator+HierarchyParsingAPI.m
  27. +15 −15 OutputGenerator+HierarchySubclassAPI.h → XMLBasedOutputGenerator+HierarchySubclassAPI.h
  28. +3 −3 OutputGenerator+HierarchySubclassAPI.m → XMLBasedOutputGenerator+HierarchySubclassAPI.m
  29. +4 −4 OutputGenerator+IndexParsingAPI.h → XMLBasedOutputGenerator+IndexParsingAPI.h
  30. +4 −4 OutputGenerator+IndexParsingAPI.m → XMLBasedOutputGenerator+IndexParsingAPI.m
  31. +15 −15 OutputGenerator+IndexSubclassAPI.h → XMLBasedOutputGenerator+IndexSubclassAPI.h
  32. +3 −3 OutputGenerator+IndexSubclassAPI.m → XMLBasedOutputGenerator+IndexSubclassAPI.m
  33. +4 −4 OutputGenerator+ObjectParsingAPI.h → XMLBasedOutputGenerator+ObjectParsingAPI.h
  34. +4 −4 OutputGenerator+ObjectParsingAPI.m → XMLBasedOutputGenerator+ObjectParsingAPI.m
  35. +37 −37 OutputGenerator+ObjectSubclassAPI.h → XMLBasedOutputGenerator+ObjectSubclassAPI.h
  36. +3 −3 OutputGenerator+ObjectSubclassAPI.m → XMLBasedOutputGenerator+ObjectSubclassAPI.m
  37. +224 −0 XMLBasedOutputGenerator.h
  38. +639 −0 XMLBasedOutputGenerator.m
  39. +29 −35 DoxygenConverter+CleanXML.h → XMLOutputGenerator.h
  40. +66 −30 DoxygenConverter+CleanXML.m → XMLOutputGenerator.m
  41. +98 −78 appledoc.xcodeproj/project.pbxproj
View
@@ -27,6 +27,7 @@ as a singleton.
{
NSMutableArray* commandLineArguments;
NSMutableDictionary* parameters;
+ NSString* outputDoxygenXMLPath;
NSString* globalTemplatesPath;
}
@@ -225,6 +226,17 @@ and @c docsetutil. */
/// @name Properties - internal
//////////////////////////////////////////////////////////////////////////////////////////
+/** The full path to the doxygen output files.
+
+Note that this property is handled differently from others - by default it is set to
+@c outputPath(), however doxygen handler should read the actual value from the doxygen
+configuration file and set it here so that the rest of the application can use it.
+
+Since doxygen generation is the first this that gets generated, the path is properly
+setup for all dependent generators automatically.
+*/
+@property(copy) NSString* outputDoxygenXMLPath;
+
/** The full path to the output clean XML files. */
@property(readonly) NSString* outputCleanXMLPath;
View
@@ -410,6 +410,9 @@ - (void) postProcessCommandLineArguments
[self replaceTemplatePlaceholdersForKey:kTKCmdOutputDocSetResourcesPathKey];
[self replaceTemplatePlaceholdersForKey:kTKCmdOutputDocSetDocumentsPathKey];
+ // Setup the default doxygen output XML path.
+ self.outputDoxygenXMLPath = self.outputPath;
+
// Make sure the documentation set bundle ID ends with .docset.
if (![self.docsetBundleID hasSuffix:@".docset"])
{
@@ -1016,4 +1019,10 @@ - (NSString*) outputDocSetDocumentsPath
return [parameters objectForKey:kTKCmdOutputDocSetDocumentsPathKey];
}
+//////////////////////////////////////////////////////////////////////////////////////////
+#pragma mark Synthetized properties
+//////////////////////////////////////////////////////////////////////////////////////////
+
+@synthesize outputDoxygenXMLPath;
+
@end
View
@@ -0,0 +1,43 @@
+//
+// Constants.h
+// appledoc
+//
+// Created by Tomaz Kragelj on 12.6.09.
+// Copyright (C) 2009, Tomaz Kragelj. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+extern NSString* kTKConverterException;
+extern NSString* kTKPlaceholderExtension;
+
+extern NSString* kTKDirClasses;
+extern NSString* kTKDirCategories;
+extern NSString* kTKDirProtocols;
+extern NSString* kTKDirCSS;
+extern NSString* kTKDirDocSet;
+
+extern NSString* kTKDataMainIndexKey;
+extern NSString* kTKDataMainHierarchyKey;
+extern NSString* kTKDataMainHierarchiesKey;
+extern NSString* kTKDataMainObjectsKey;
+extern NSString* kTKDataMainDirectoriesKey;
+
+extern NSString* kTKDataHierarchyObjectNameKey;
+extern NSString* kTKDataHierarchyObjectDataKey;
+extern NSString* kTKDataHierarchyChildrenKey;
+extern NSString* kTKDataHierarchyTempKey;
+
+extern NSString* kTKDataObjectNameKey;
+extern NSString* kTKDataObjectKindKey;
+extern NSString* kTKDataObjectClassKey;
+extern NSString* kTKDataObjectMarkupKey;
+extern NSString* kTKDataObjectMembersKey;
+extern NSString* kTKDataObjectParentKey;
+extern NSString* kTKDataObjectRelDirectoryKey;
+extern NSString* kTKDataObjectRelPathKey;
+extern NSString* kTKDataObjectDoxygenFilenameKey;
+
+extern NSString* kTKDataMemberNameKey;
+extern NSString* kTKDataMemberPrefixKey;
+extern NSString* kTKDataMemberSelectorKey;
View
@@ -0,0 +1,60 @@
+//
+// Constants.m
+// appledoc
+//
+// Created by Tomaz Kragelj on 12.6.09.
+// Copyright (C) 2009, Tomaz Kragelj. All rights reserved.
+//
+
+#import "Constants.h"
+
+//////////////////////////////////////////////////////////////////////////////////////////
+#pragma mark Exception names
+//////////////////////////////////////////////////////////////////////////////////////////
+
+NSString* kTKConverterException = @"TKConverterException";
+
+//////////////////////////////////////////////////////////////////////////////////////////
+#pragma mark Placeholder strings
+//////////////////////////////////////////////////////////////////////////////////////////
+
+NSString* kTKPlaceholderExtension = @"$EXTENSION";
+
+//////////////////////////////////////////////////////////////////////////////////////////
+#pragma mark Common directory structure
+//////////////////////////////////////////////////////////////////////////////////////////
+
+NSString* kTKDirClasses = @"Classes";
+NSString* kTKDirCategories = @"Categories";
+NSString* kTKDirProtocols = @"Protocols";
+NSString* kTKDirCSS = @"css";
+NSString* kTKDirDocSet = @"docset";
+
+//////////////////////////////////////////////////////////////////////////////////////////
+#pragma mark Database keys
+//////////////////////////////////////////////////////////////////////////////////////////
+
+NSString* kTKDataMainIndexKey = @"Index"; // NSXMLDocument
+NSString* kTKDataMainHierarchyKey = @"Hierarchy"; // NSXMLDocument
+NSString* kTKDataMainHierarchiesKey = @"Hierarchies"; // NSDictionary
+NSString* kTKDataMainObjectsKey = @"Objects"; // NSDictionary
+NSString* kTKDataMainDirectoriesKey = @"Directories"; // NSDictionary
+
+NSString* kTKDataHierarchyObjectNameKey = @"ObjectName"; // NSString
+NSString* kTKDataHierarchyObjectDataKey = @"ObjectData"; // NSDictionary
+NSString* kTKDataHierarchyChildrenKey = @"Children"; // NSString
+NSString* kTKDataHierarchyTempKey = @"TEMPORARY"; // NSNumber / BOOL
+
+NSString* kTKDataObjectNameKey = @"ObjectName"; // NSString
+NSString* kTKDataObjectKindKey = @"ObjectKind"; // NSString
+NSString* kTKDataObjectClassKey = @"ObjectClass"; // NSString
+NSString* kTKDataObjectMarkupKey = @"CleanedMarkup"; // NSXMLDocument
+NSString* kTKDataObjectMembersKey = @"Members"; // NSDictionary
+NSString* kTKDataObjectParentKey = @"Parent"; // NSString
+NSString* kTKDataObjectRelDirectoryKey = @"RelativeDirectory"; // NSString
+NSString* kTKDataObjectRelPathKey = @"RelativePath"; // NSString
+NSString* kTKDataObjectDoxygenFilenameKey = @"DoxygenMarkupFilename"; // NSString
+
+NSString* kTKDataMemberNameKey = @"Name"; // NSString
+NSString* kTKDataMemberPrefixKey = @"Prefix"; // NSString
+NSString* kTKDataMemberSelectorKey = @"Selector"; // NSString
@@ -1,26 +1,34 @@
//
-// DoxygenConverter+DocSet.h
+// DocSetOutputGenerator.h
// appledoc
//
-// Created by Tomaz Kragelj on 17.4.09.
-// Copyright 2009 Tomaz Kragelj. All rights reserved.
+// Created by Tomaz Kragelj on 11.6.09.
+// Copyright (C) 2009, Tomaz Kragelj. All rights reserved.
//
-#import <Foundation/Foundation.h>
-#import "DoxygenConverter.h"
+#import "OutputGenerator.h"
//////////////////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////
-/** Implements documentation set related functionality for @c DoxygenConverter class.
+/** Defines a concrete @c OutputGenerator which generates documentation set.
-This category creates the documentation set info plist and all required files required for
-indexing the documentation set, it handles the indexing itself and prepares the
-documentation set bundle as well as installs it to the @c Xcode documentation.
+The generator depends on @c XMLOutputGenerator and @c XHTMLOutputGenerator output. It
+generates the documentation set source plist, index and nodes XML source files, invokes
+indexing through the @c docsetutils command line utility and installs the documentation
+set to the Xcode documentation window.
+
+Since the @c DocSetOutputGenerator doesn't generate the actual content files itself, it
+must be given the locations, names and extensions of the source files. This should be
+set through the @c documentationFilesInfoProvider() property before generation starts. If the
+clients forget to set this property, generation will fail immediately.
*/
-@interface DoxygenConverter (DocSet)
+@interface DocSetOutputGenerator : OutputGenerator
+{
+ id<OutputInfoProvider> documentationFilesInfoProvider;
+}
//////////////////////////////////////////////////////////////////////////////////////////
-/// @name Documentation set creation handling
+/// @name Documentation set handling
//////////////////////////////////////////////////////////////////////////////////////////
/** Creates the DocSet source plist file.
@@ -29,7 +37,8 @@ This file is used when creating the documentation set. The file is only created
doesn't exist yet. If it exists, this method will exit without doing anything. This
allows the user to change the data in the file as he see fit after it was created.
-This message is automatically sent from @c DoxygenConverter::convert() in the proper order.
+This message is automatically sent from @c generateSpecificOutput() in the proper order.
+It is not designed to be sent manually from the clients.
@exception NSException Thrown if creating the plist file fails.
@see createDocSetNodesFile
@@ -44,7 +53,8 @@ The Nodes.xml file describes the structure of the documentation set and is used
create a table of contents that users see in the Xcode documentation window. This file
is required when compiling the documentation set.
-This message is automatically sent from @c DoxygenConverter::convert() in the proper order.
+This message is automatically sent from @c generateSpecificOutput() in the proper order.
+It is not designed to be sent manually from the clients.
@exception NSException Thrown if creation fails.
@see createDocSetSourcePlistFile
@@ -59,7 +69,8 @@ This message is automatically sent from @c DoxygenConverter::convert() in the pr
The Tokens.xml file associate symbol names with locations in the documentation files.
This file is used for creating the symbol index for the documentation set.
-This message is automatically sent from @c DoxygenConverter::convert() in the proper order.
+This message is automatically sent from @c generateSpecificOutput() in the proper order.
+It is not designed to be sent manually from the clients.
@exception NSException Thrown if creation fails.
@see createDocSetSourcePlistFile
@@ -75,12 +86,14 @@ have been created. It will copy all html files created in @c createCleanOutputDo
to the DocSet output directory and will invoke the indexing of the files with the help of
nodes and tokes files.
-This message is automatically sent from @c DoxygenConverter::convert() in the proper order.
+This message is automatically sent from @c generateSpecificOutput() in the proper order.
+It is not designed to be sent manually from the clients.
@exception NSException Thrown if creation fails.
@see createDocSetSourcePlistFile
@see createDocSetNodesFile
@see createDocSetTokesFile
+@see addDocSetNodeToElement:fromHierarchyData:
*/
- (void) createDocSetBundle;
@@ -98,4 +111,16 @@ will recursively add all subnodes as well.
- (void) addDocSetNodeToElement:(NSXMLElement*) parent
fromHierarchyData:(NSDictionary*) data;
+//////////////////////////////////////////////////////////////////////////////////////////
+/// @name Properties
+//////////////////////////////////////////////////////////////////////////////////////////
+
+/** Sets or returns the @c OutputInfoProvider conformer that provides information about
+source files.
+
+@warning Clients need to set this before starting output generation. If they fail to
+ provide a valid object, generation immediately fails with an exception.
+*/
+@property(retain) id<OutputInfoProvider> documentationFilesInfoProvider;
+
@end
@@ -1,18 +1,63 @@
//
-// DoxygenConverter+DocSet.m
+// DocSetOutputGenerator.m
// appledoc
//
-// Created by Tomaz Kragelj on 17.4.09.
-// Copyright 2009 Tomaz Kragelj. All rights reserved.
+// Created by Tomaz Kragelj on 11.6.09.
+// Copyright (C) 2009, Tomaz Kragelj. All rights reserved.
//
-#import "DoxygenConverter+DocSet.h"
-#import "XHTMLOutputGenerator.h"
+#import "DocSetOutputGenerator.h"
#import "CommandLineParser.h"
#import "LoggingProvider.h"
#import "Systemator.h"
-@implementation DoxygenConverter (DocSet)
+@implementation DocSetOutputGenerator
+
+//////////////////////////////////////////////////////////////////////////////////////////
+#pragma mark Specific output generation entry points
+//////////////////////////////////////////////////////////////////////////////////////////
+
+//----------------------------------------------------------------------------------------
+- (BOOL) isOutputGenerationEnabled
+{
+ return cmd.createDocSet;
+}
+
+//----------------------------------------------------------------------------------------
+- (void) generateSpecificOutput
+{
+ if (!self.documentationFilesInfoProvider)
+ [Systemator throwExceptionWithName:kTKConverterException
+ withDescription:@"documentationFilesInfoProvider not set"];
+
+ [self createDocSetSourcePlistFile];
+ [self createDocSetNodesFile];
+ [self createDocSetTokesFile];
+ [self createDocSetBundle];
+}
+
+//----------------------------------------------------------------------------------------
+- (void) createOutputDirectories
+{
+ // Note that we only manually create temporary documentation set directory here,
+ // if the documentation set is installed, it will be copied as a bundle to the
+ // appropriate path.
+ [Systemator createDirectory:cmd.outputDocSetPath];
+ [Systemator createDirectory:cmd.outputDocSetContentsPath];
+ [Systemator createDirectory:cmd.outputDocSetResourcesPath];
+}
+
+//----------------------------------------------------------------------------------------
+- (void) removeOutputDirectories
+{
+ // Note that we only remove temporary documentation set directory here, the installed
+ // copy is always left in it's installation directory.
+ [Systemator removeItemAtPath:cmd.outputDocSetPath];
+}
+
+//////////////////////////////////////////////////////////////////////////////////////////
+#pragma mark Documentation set handling
+//////////////////////////////////////////////////////////////////////////////////////////
//----------------------------------------------------------------------------------------
- (void) createDocSetSourcePlistFile
@@ -88,8 +133,8 @@ - (void) createDocSetNodesFile
logNormal(@"Creating DocSet Nodes.xml file...");
NSAutoreleasePool* loopAutoreleasePool = [[NSAutoreleasePool alloc] init];
NSXMLDocument* document = [NSXMLDocument document];
- NSString* indexFileName = [XHTMLOutputGenerator indexFileName];
- NSString* hierarchyFileName = [XHTMLOutputGenerator hierarchyFileName];
+ NSString* indexFileName = [documentationFilesInfoProvider outputIndexFilename];
+ NSString* hierarchyFileName = [documentationFilesInfoProvider outputHierarchyFilename];
// Create the version and ecoding elements.
[document setVersion:@"1.0"];
@@ -137,8 +182,7 @@ - (void) createDocSetNodesFile
for (NSDictionary* objectData in directoryObjects)
{
NSString* objectName = [objectData objectForKey:kTKDataObjectNameKey];
- NSString* objectPath = [objectData objectForKey:kTKDataObjectRelPathKey];
- objectPath = [XHTMLOutputGenerator pathByReplacingPlaceholders:objectPath];
+ NSString* objectPath = [documentationFilesInfoProvider outputObjectFilenameForObject:objectData];
NSXMLElement* objectElement = [NSXMLNode elementWithName:@"Node"];
[directorySubnodesElement addChild:objectElement];
@@ -208,8 +252,7 @@ - (void) createDocSetTokesFile
NSDictionary* objectData = [objects objectForKey:objectName];
NSXMLDocument* objectDocument = [objectData objectForKey:kTKDataObjectMarkupKey];
NSString* objectKind = [objectData objectForKey:kTKDataObjectKindKey];
- NSString* objectRelPath = [objectData objectForKey:kTKDataObjectRelPathKey];
- objectRelPath = [XHTMLOutputGenerator pathByReplacingPlaceholders:objectRelPath];
+ NSString* objectRelPath = [documentationFilesInfoProvider outputObjectFilenameForObject:objectData];
// Prepare the object identifier.
NSString* objectIdentifier = nil;
@@ -346,8 +389,7 @@ - (void) createDocSetBundle
NSString* message = [NSString stringWithFormat:@"Installation of DocSet failed with message:\n'%@'!",
[errorDict objectForKey:NSAppleScriptErrorMessage]];
logError(@"Failed installing DocSet to Xcode documentation!");
- [Systemator throwExceptionWithName:kTKConverterException
- withDescription:message];
+ [Systemator throwExceptionWithName:kTKConverterException withDescription:message];
}
[installScript release];
@@ -387,8 +429,8 @@ - (void) addDocSetNodeToElement:(NSXMLElement*) parent
NSString* objectName = [data objectForKey:kTKDataHierarchyObjectNameKey];
NSString* objectPath = [objectData objectForKey:kTKDataObjectRelPathKey];
objectPath = objectPath ?
- [XHTMLOutputGenerator pathByReplacingPlaceholders:objectPath] :
- [XHTMLOutputGenerator hierarchyFileName];
+ [documentationFilesInfoProvider outputObjectFilenameForObject:objectData] :
+ [documentationFilesInfoProvider outputHierarchyFilename];
// Create the main node that will represent the object.
NSXMLElement* node = [NSXMLNode elementWithName:@"Node"];
@@ -417,4 +459,10 @@ - (void) addDocSetNodeToElement:(NSXMLElement*) parent
}
}
+//////////////////////////////////////////////////////////////////////////////////////////
+#pragma mark Properties
+//////////////////////////////////////////////////////////////////////////////////////////
+
+@synthesize documentationFilesInfoProvider;
+
@end
Oops, something went wrong.

0 comments on commit 3a46c43

Please sign in to comment.