XMLOutputGenerator.m

//
//  XMLOutputGenerator.m
//  appledoc
//
//  Created by Tomaz Kragelj on 11.6.09.
//  Copyright (C) 2009, Tomaz Kragelj. All rights reserved.
//

#import "XMLOutputGenerator.h"
#import "CommandLineParser.h"
#import "LoggingProvider.h"
#import "Systemator.h"

@implementation XMLOutputGenerator

//////////////////////////////////////////////////////////////////////////////////////////
#pragma mark OutputInfoProvider protocol implementation
//////////////////////////////////////////////////////////////////////////////////////////

//----------------------------------------------------------------------------------------
- (NSString*) outputFilesExtension
{
	return @".xml";
}

//----------------------------------------------------------------------------------------
- (NSString*) outputBasePath
{
	return [cmd.outputPath stringByAppendingPathComponent:@"cxml"];
}

//////////////////////////////////////////////////////////////////////////////////////////
#pragma mark Specific output generation entry points
//////////////////////////////////////////////////////////////////////////////////////////

//----------------------------------------------------------------------------------------
- (void) generateSpecificOutput
{
	if (!self.doxygenInfoProvider)
		[Systemator throwExceptionWithName:kTKConverterException
						   withDescription:@"doxygenInfoProvider not set"];
	
	[self createCleanObjectDocumentationMarkup];
	[self mergeCleanCategoriesToKnownObjects];
	[self updateCleanObjectsDatabase];
	[self createCleanIndexDocumentationFile];
	[self createCleanHierarchyDocumentationFile];
	[self fixCleanObjectDocumentation];
	[self saveCleanObjectDocumentationFiles];
}

//////////////////////////////////////////////////////////////////////////////////////////
#pragma mark Clean XML handling
//////////////////////////////////////////////////////////////////////////////////////////

//----------------------------------------------------------------------------------------
- (void) createCleanObjectDocumentationMarkup
{
	logNormal(@"Creating clean object XML files...");
	NSAutoreleasePool* loopAutoreleasePool = nil;
	NSError* error = nil;
	
	// First get the list of all files (and directories) at the doxygen output path. Note
	// that we only handle certain files, based on their names.
	NSString* searchPath = [self.doxygenInfoProvider outputBasePath];
	NSArray* files = [manager contentsOfDirectoryAtPath:searchPath error:&error];
	if (!files)
	{
		logError(@"Failed enumerating files at '%@'!", searchPath);
		[Systemator throwExceptionWithName:kTKConverterException basedOnError:error];
	}
	
	for (NSString* filename in files)
	{
		// Setup the autorelease pool for this iteration. Note that we are releasing the
		// previous iteration pool here as well. This is because we use continue to 
		// skip certain iterations, so releasing at the end of the loop would not work...
		// Also note that after the loop ends, we are releasing the last iteration loop.
		[loopAutoreleasePool drain];
		loopAutoreleasePool = [[NSAutoreleasePool alloc] init];
		
		// (1) First check if the file is .xml and starts with correct name.
		BOOL parse = [filename hasSuffix:@".xml"];
		parse &= [filename hasPrefix:@"class_"] ||
				 [filename hasPrefix:@"interface_"] ||
				 [filename hasPrefix:@"protocol_"];
		if (!parse)
		{
			logDebug(@"- Skipping '%@' because it doesn't describe known object.", filename);
			continue;
		}
		
		// (2) Parse the XML and check if the file is documented or not. Basically
		// we check if at least one brief or detailed description contains a
		// para tag. If so, the document is considered documented... If parsing
		// fails, log and skip the file.
		NSString* inputFilename = [searchPath stringByAppendingPathComponent:filename];
		NSURL* originalURL = [NSURL fileURLWithPath:inputFilename];
		NSXMLDocument* originalDocument = [[[NSXMLDocument alloc] initWithContentsOfURL:originalURL
																				options:0
																				  error:&error] autorelease];
		if (!originalDocument)
		{
			logError(@"Skipping '%@' because parsing failed with error %@!", 
					 filename, 
					 [error localizedDescription]);
			continue;
		}
		
		// (3) If at least one item is documented, run the document through the
		// xslt converter to get clean XML. Then use the clean XML to get
		// further object information and finally add the object to the data
		// dictionary.
		if ([[originalDocument nodesForXPath:@"//briefdescription/para" error:NULL] count] == 0 &&
			[[originalDocument nodesForXPath:@"//detaileddescription/para" error:NULL] count] == 0)
		{
			logVerbose(@"- Skipping '%@' because it contains non-documented object...", filename);
			continue;
		}

		// (4) Prepare file names and run the xslt converter. Catch any exception
		// and log it, then continue with the next file.
		@try
		{
			// (A) Run the xslt converter.
			NSString* stylesheetFile = [cmd.templatesPath stringByAppendingPathComponent:@"object.xslt"];
			NSXMLDocument* cleanDocument = [Systemator applyXSLTFromFile:stylesheetFile 
															  toDocument:originalDocument
																   error:&error];
			if (!cleanDocument)
			{
				logError(@"Skipping '%@' because creating clean XML failed with error %@!", 
						 filename, 
						 [error localizedDescription]);
				continue;
			}

			// (B) If object node is not present, exit. This means the convertion failed...
			NSArray* objectNodes = [cleanDocument nodesForXPath:@"/object" error:NULL];
			if ([objectNodes count] == 0)
			{
				logError(@"Skipping '%@' because object node not found!", filename);
				continue;
			}
			
			// (C) Get object name node and append utility version to xml. If not found, exit.
			NSXMLElement* objectNode = [objectNodes objectAtIndex:0];
			NSArray* objectNameNodes = [objectNode nodesForXPath:@"name" error:NULL];
			if ([objectNameNodes count] == 0)
			{
				logError(@"Skipping '%@' because object name node not found!", filename);
				continue;
			}
			[objectNode addAttribute:[NSXMLNode attributeWithName:@"generator" stringValue:cmd.generator]];
			
			// (D) Now we have all information, get the data and add the object to the list.
			NSXMLElement* objectNameNode = [objectNameNodes objectAtIndex:0];
			NSString* objectName = [objectNameNode stringValue];
			NSString* objectKind = [[objectNode attributeForName:@"kind"] stringValue];
			if ([objectName length] == 0 || [objectKind length] == 0)
			{
				logError(@"Skipping '%@' because data cannot be collected (name %@, kind %@)!",
						 filename,
						 objectName,
						 objectKind);
				continue;
			}
			
			// (D.1) Prepare the object's parent. If the object doesn't have parent, 
			// just assume it's derived from NSObject, as long it's not NSObject itself.
			// There's a bug in doxygen implementation which doesn't list some super
			// classes - NSManagedObject for example...
			// Although this doesn't properly work, at least the objects appear on the
			// hierarchy. Note that we only do this for classes!
			NSString* objectParent = nil;
			NSArray* baseNodes = [objectNode nodesForXPath:@"base" error:nil];
			if ([baseNodes count] == 0 && [objectKind isEqualToString:@"class"])
			{
				if (![objectName isEqualToString:@"NSObject"]) {
					logInfo(@"- %@ class marked with no base, assuming NSObject!", objectName);
					NSXMLElement* baseNode = [NSXMLElement elementWithName:@"base" stringValue:@"NSObject"];
					[objectNode addChild:baseNode];
					baseNodes = [objectNode nodesForXPath:@"base" error:nil];
				}
			}
			if ([baseNodes count] > 0) objectParent = [[baseNodes objectAtIndex:0] stringValue];
			
			// (E) Prepare the object relative directory and relative path to the index.
			// Also set the class "link" for categories.
			NSString* objectClass = nil;
			NSString* objectRelativeDirectory = nil;
			if ([objectKind isEqualToString:@"category"])
			{
				objectRelativeDirectory = kTKDirCategories;
				NSRange categoryNameRange = [objectName rangeOfString:@"("];
				if (categoryNameRange.location != NSNotFound)
				{
					objectClass = [objectName substringToIndex:categoryNameRange.location];
				}
			}
			else if ([objectKind isEqualToString:@"protocol"])
			{
				objectRelativeDirectory = kTKDirProtocols;
			}
			else
			{
				objectRelativeDirectory = kTKDirClasses;
			}
			
			NSString* objectRelativePath = [objectRelativeDirectory stringByAppendingPathComponent:objectName];
			objectRelativePath = [objectRelativePath stringByAppendingString:kTKPlaceholderExtension];
			
			// (F) OK, now really add the node to the database... ;) First create the
			// object's description dictionary. Then add the object to the Objects
			// dictionary. Then check if the object's relative directory key already
			// exists in the directories dictionary. If not, create it, then add the
			// object to the end of the list.
			NSMutableDictionary* objectData = [[NSMutableDictionary alloc] init];
			[objectData setObject:objectName forKey:kTKDataObjectNameKey];
			[objectData setObject:objectKind forKey:kTKDataObjectKindKey];
			[objectData setObject:cleanDocument forKey:kTKDataObjectMarkupKey];
			[objectData setObject:objectRelativeDirectory forKey:kTKDataObjectRelDirectoryKey];
			[objectData setObject:objectRelativePath forKey:kTKDataObjectRelPathKey];
			[objectData setObject:inputFilename forKey:kTKDataObjectDoxygenFilenameKey];
			if (objectParent) [objectData setObject:objectParent forKey:kTKDataObjectParentKey];
			if (objectClass) [objectData setObject:objectClass forKey:kTKDataObjectClassKey];
			
			// Add the object to the object's dictionary.
			NSMutableDictionary* objectsDict = [database objectForKey:kTKDataMainObjectsKey];
			[objectsDict setObject:objectData forKey:objectName];
			
			// Add the object to the directories list.
			NSMutableDictionary* directoriesDict = [database objectForKey:kTKDataMainDirectoriesKey];
			NSMutableArray* directoryArray = [directoriesDict objectForKey:objectRelativeDirectory];
			if (directoryArray == nil)
			{
				directoryArray = [NSMutableArray array];
				[directoriesDict setObject:directoryArray forKey:objectRelativeDirectory];
			}
			[directoryArray addObject:objectData];
			
			// Log the object.
			logVerbose(@"- Found '%@' of type '%@' in file '%@'...", 
					   objectName, 
					   objectKind,
					   filename);
		}
		@catch (NSException* e)
		{
			logError(@"Skipping '%@' because converting to clean documentation failed with error %@!", 
					 filename, 
					 [e reason]);
			continue;
		}
	}
	
	// Release the last iteration pool.
	[loopAutoreleasePool drain];	
	logInfo(@"Finished creating clean object documentation files.");
}

//----------------------------------------------------------------------------------------
- (void) mergeCleanCategoriesToKnownObjects
{
	if (cmd.mergeKnownCategoriesToClasses)
	{
		logNormal(@"Merging categories documentation to known classes...");
		
		// Go through all categories and check if they belong to a known class. If so
		// merge the documentation as a new section at the end of the class documentation.
		// Then remember the category name so we can later remove it from the database. 
		NSMutableArray* removedCategories = [NSMutableArray array];
		NSMutableDictionary* objects = [database objectForKey:kTKDataMainObjectsKey];
		NSDictionary* directoriesDict = [database objectForKey:kTKDataMainDirectoriesKey];
		NSMutableArray* categoriesArray = [directoriesDict objectForKey:kTKDirCategories];
		for (NSDictionary* categoryData in categoriesArray)
		{
			NSString* categoryName = [categoryData objectForKey:kTKDataObjectNameKey];
			NSString* className = [categoryData objectForKey:kTKDataObjectClassKey];
			if (!className)
			{
				logVerbose(@"- Skipping '%@' because it belongs to unknown class.", categoryName);
				continue;
			}
			
			logVerbose(@"- Merging category '%@' documentation to class '%@'...",
					   categoryName,
					   className);
			
			// Get the main class XML.
			NSDictionary* classData = [objects objectForKey:className];
			NSXMLDocument* classDocument = [classData objectForKey:kTKDataObjectMarkupKey];
			
			// Get the main class <sections> container element. If not found, exit.
			// (this should not really happen, since the xslt adds "Others" node by
			// default, but let's keep it safe). If there's more than one sections node,
			// use the first one (also should not happen).
			NSXMLElement* classSectionsNode = nil;
			NSArray* classSectionsNodes = [classDocument nodesForXPath:@"/object/sections" error:nil];
			if ([classSectionsNodes count] == 0) 
			{
				logInfo(@"Skipping '%@' because class doesn't contain sections node!", categoryName);
				continue;					
			}
			classSectionsNode = (NSXMLElement*)[classSectionsNodes objectAtIndex:0];

			// Get the category clean document markup. Next step depends on the category
			// merging optios. If sections need to be preserved, we should copy all
			// sections. Otherwise we should create one section for each category which
			// includes members from all sections.
			NSXMLDocument* categoryDocument = [categoryData objectForKey:kTKDataObjectMarkupKey];
			if (cmd.keepMergedCategorySections)
			{
				// Get the array of all category sections and append them in the same
				// order to the main class. The new section name should have the category
				// name prepended.
				NSArray* categorySectionNodes = [categoryDocument nodesForXPath:@"/object/sections/section" error:nil];
				for (NSXMLElement* categorySectionNode in categorySectionNodes)
				{
					// Get category section name. Use empty string by default just in case...
					NSString* categorySectionName = @"";
					NSArray* categorySectionNameNodes = [categorySectionNode nodesForXPath:@"name" error:nil];
					if ([categorySectionNameNodes count] > 0)
					{
						NSXMLNode* nameNode = [categorySectionNameNodes objectAtIndex:0];
						categorySectionName = [nameNode stringValue];
					}
					
					// Merge the section data to the main class document. We need to prepend
					// the category name before the section description before... Note that
					// we handle the cases where no category name is defined by simply using
					// the category section name.
					logDebug(@"  - Merging documentation for section '%@'...");
					NSXMLElement* classSectionNode = [categorySectionNode copy];
					NSArray* classSectionNameNodes = [classSectionNode nodesForXPath:@"name" error:nil];
					if ([classSectionNameNodes count] > 0)
					{					
						NSString* extensionName = [categoryName substringFromIndex:[className length]];
						extensionName = [extensionName substringWithRange:NSMakeRange(1, [extensionName length]-2)];
						NSString* classSectionName = categorySectionName;
						if ([extensionName length] > 0)
							classSectionName = [NSString stringWithFormat:@"%@ / %@", 
												extensionName,
												categorySectionName];
						NSXMLNode* nameNode = [classSectionNameNodes objectAtIndex:0];
						[nameNode setStringValue:classSectionName];
					}
					[classSectionsNode addChild:classSectionNode];
					[classSectionNode release];
				}
			}
			else
			{
				logDebug(@"  - Merging all sections to '%@'...", categoryName);
				
				// Create the class section element.
				NSXMLElement* sectionNode = [NSXMLNode elementWithName:@"section"];
				NSXMLElement* sectionNameNode = [NSXMLNode elementWithName:@"name" stringValue:categoryName];
				[sectionNode addChild:sectionNameNode];
				
				// Get all member documentation for all sections and add each one to the
				// class section element.
				NSArray* memberNodes = [categoryDocument nodesForXPath:@"/object/sections/section/member" error:nil];
				for (NSXMLElement* memberNode in memberNodes)
				{
					NSXMLElement* classMemberNode = [memberNode copy];
					[sectionNode addChild:classMemberNode];
					[classMemberNode release];
				}
				
				// Append the section data to the main class document.
				[classSectionsNode addChild:sectionNode];
			}
			
			// After the category was added, add it's <file> tag to the end of the 
			// last one. This will be used in actual output generation to show all
			// source files from which documentation was extracted. Note that we skip
			// all files which were already added.
			NSArray* categoryFileNodes = [categoryDocument nodesForXPath:@"object/file" error:nil];
			if ([categoryFileNodes count] > 0)
			{
				NSArray* classFileNodes = [classDocument nodesForXPath:@"object/file" error:nil];
				if ([classFileNodes count] > 0)
				{
					NSXMLElement* lastClassFileNode = [classFileNodes lastObject];
					NSXMLElement* parentNode = (NSXMLElement*)[lastClassFileNode parent];
					NSUInteger index = [lastClassFileNode index];
					for (NSXMLElement* categoryFileNode in categoryFileNodes)
					{
						NSString* testQuery = [NSString stringWithFormat:@"object/file[%@]", 
											   [categoryFileNode stringValue]];
						if ([[classDocument nodesForXPath:testQuery error:nil] count] == 0)
						{
							logDebug(@"  - Inserting file '%@' from category to index %d...",
									 [categoryFileNode stringValue],
									 index);						
							NSXMLElement* insertedNode = [categoryFileNode copy];
							[parentNode insertChild:insertedNode atIndex:index + 1];
							[insertedNode release];
							index++;
						}
					}
				}
			}
			
			// Remember the category name which was removed. Note that we use category
			// data because we can get all information from there and we need the
			// instance to properly remove from the directories array.
			[removedCategories addObject:categoryData];
		}
		
		
		// Remove all category "stand alone" documentation from the database. We'll
		// lose the category description this way, but this usually doesn't provide
		// much information (at least not in my documentation... ;-)).
		for (NSDictionary* categoryData in removedCategories)
		{
			NSString* categoryName = [categoryData objectForKey:kTKDataObjectNameKey];
			logDebug(@"  - Removing category '%@' documentation...", categoryName);
			[categoriesArray removeObject:categoryData];
			[objects removeObjectForKey:categoryName];
		}
				
		logInfo(@"Finished merging categories documentation to known classes...");
	}
}

//----------------------------------------------------------------------------------------
- (void) updateCleanObjectsDatabase
{
	logNormal(@"Updating clean objects database...");
	
	// Prepare common variables to optimize loop a bit.
	NSAutoreleasePool* loopAutoreleasePool = nil;
	
	// Handle all files in the database.
	NSDictionary* objects = [database objectForKey:kTKDataMainObjectsKey];
	for (NSString* objectName in objects)
	{
		// Setup the autorelease pool for this iteration. Note that we are releasing the
		// previous iteration pool here as well. This is because we use continue to 
		// skip certain iterations, so releasing at the end of the loop would not work...
		// Also note that after the loop ends, we are releasing the last iteration loop.
		[loopAutoreleasePool drain];
		loopAutoreleasePool = [[NSAutoreleasePool alloc] init];
		
		// Get the required object data.
		NSMutableDictionary* objectData = [objects objectForKey:objectName];
		logVerbose(@"- Handling '%@'...", objectName);
		
		[self createMembersDataForObject:objectName objectData:objectData];
	}
	
	// Release last iteration pool.
	[loopAutoreleasePool drain];
	logInfo(@"Finished updating clean objects database.");
}

//----------------------------------------------------------------------------------------
- (void) createCleanIndexDocumentationFile
{
	logNormal(@"Creating clean index documentation file...");	
	NSAutoreleasePool* loopAutoreleasePool = [[NSAutoreleasePool alloc] init];
	
	// Create the default markup.
	NSXMLDocument* document = [[NSXMLDocument alloc] init];
	NSXMLElement* projectElement = [NSXMLElement elementWithName:@"project"];
	[projectElement addAttribute:[NSXMLNode attributeWithName:@"generator" stringValue:cmd.generator]];
	[document setVersion:@"1.0"];
	[document addChild:projectElement];
	
	// Enumerate through all the enumerated objects and create the markup. Note that
	// we use directory structure so that we get proper enumeration.
	NSDictionary* objects = [database objectForKey:kTKDataMainObjectsKey];
	NSArray* sortedObjectNames = [[objects allKeys] sortedArrayUsingSelector:@selector(compare:)];
	for (NSString* objectName in sortedObjectNames)
	{
		logVerbose(@"- Handling '%@'...", objectName);
		
		NSDictionary* objectData = [objects valueForKey:objectName];
		NSString* objectKind = [objectData valueForKey:kTKDataObjectKindKey];
		NSString* objectRef = [objectData valueForKey:kTKDataObjectRelPathKey];
		
		// Create the object element and the kind and id attributes.
		NSXMLElement* objectElement = [NSXMLElement elementWithName:@"object"];
		NSXMLNode* kindAttribute = [NSXMLNode attributeWithName:@"kind" stringValue:objectKind];
		NSXMLNode* idAttribute = [NSXMLNode attributeWithName:@"id" stringValue:objectRef];
		[objectElement addAttribute:kindAttribute];
		[objectElement addAttribute:idAttribute];
		[projectElement addChild:objectElement];
		
		// Create the name element.
		NSXMLElement* nameElement = [NSXMLElement elementWithName:@"name"];
		[nameElement setStringValue:objectName];
		[objectElement addChild:nameElement];
	}
	
	// Store the cleaned markup to the application data.
	[database setObject:document forKey:kTKDataMainIndexKey];
	
	// Save the markup.
	NSError* error = nil;
	NSData* markupData = [document XMLDataWithOptions:NSXMLNodePrettyPrint];
	[document release];
	NSString* filename = [self outputBasePath];
	filename = [filename stringByAppendingPathComponent:[self outputIndexFilename]];
	if (![markupData writeToFile:filename options:0 error:&error])
	{
		logError(@"Failed writting clean Index.xml to '%@'!", filename);
		[Systemator throwExceptionWithName:kTKConverterException basedOnError:error];
	}
	
	[loopAutoreleasePool drain];
	logInfo(@"Finished creating clean index documentation file.");
}

//----------------------------------------------------------------------------------------
- (void) createCleanHierarchyDocumentationFile
{
	logNormal(@"Creating clean hierarchy documentation file...");
	
	// Prepare common variables.
	NSAutoreleasePool* loopAutoreleasePool = nil;
	
	// Go through all the objects in the database and prepare the hierarchy. Note that
	// this is done in two steps. In the first step the objects are stored in the
	// hierarchy in proper structure, except that the root level contains ALL of the
	// objects. However all objects which place is not in the root will have their
	// temporary flag set. These will be removed in the second pass. This way allows
	// us to simplify hieararchy generation - when adding a new object, get it's parent
	// and check if the parent already exists in the root. If not, add the parent, add
	// the object to it's children and then also add the object to the root but marked
	// with temporary...
	NSMutableDictionary* hierarchies = [database objectForKey:kTKDataMainHierarchiesKey];
	NSDictionary* objects = [database objectForKey:kTKDataMainObjectsKey];
	for (NSString* objectName in objects)
	{
		// Release all autoreleased objects from the previous iteration.
		[loopAutoreleasePool drain];
		loopAutoreleasePool = [[NSAutoreleasePool alloc] init];
		
		// Get the object data from the objects database. If parent data exists, add the
		// object to the hierarchy. Note that this adds both, the parent and the object
		// to the root.
		NSMutableDictionary* objectData = [objects objectForKey:objectName];
		NSString* parentName = [objectData objectForKey:kTKDataObjectParentKey];
		if (parentName)
		{
			logDebug(@"  - Handling '%@' as child of '%@'...", objectName, parentName);
			
			// Check the hierarchy database to see if object has already been added - this
			// can happen in the code below if the object is found as a parent of another
			// object. In such case we need to add object's data to the existing entry,
			// otherwise we need to create the data.
			NSMutableDictionary* objectHierarchyData = [hierarchies objectForKey:objectName];
			if (!objectHierarchyData)
			{
				objectHierarchyData = [NSMutableDictionary dictionary];
				[objectHierarchyData setObject:objectName forKey:kTKDataHierarchyObjectNameKey];
				[objectHierarchyData setObject:[NSMutableDictionary dictionary] forKey:kTKDataHierarchyChildrenKey];
				[hierarchies setObject:objectHierarchyData forKey:objectName];
			}
			
			// Add the pointer to the object's data dictionary and set it's temporary
			// key so that it will be removed later on - this object has a parent, so
			// it's place is not in the root.
			[objectHierarchyData setObject:objectData forKey:kTKDataHierarchyObjectDataKey];
			[objectHierarchyData setObject:[NSNumber numberWithBool:YES] forKey:kTKDataHierarchyTempKey];
			
			// Check the hierarchy database to see if parent was already handled - if
			// we find it in the root, add the object to it's children. Otherwise create
			// the data for it now (note that at this point we don't prepare full data,
			// this will be handled in above code when (if) parent object is found in
			// documented data).
			NSMutableDictionary* parentHierarchyData = [hierarchies objectForKey:parentName];
			if (!parentHierarchyData)
			{
				parentHierarchyData = [NSMutableDictionary dictionary];
				[parentHierarchyData setObject:parentName forKey:kTKDataHierarchyObjectNameKey];
				[parentHierarchyData setObject:[NSMutableDictionary dictionary] forKey:kTKDataHierarchyChildrenKey];
				[hierarchies setObject:parentHierarchyData forKey:parentName];
			}
			
			// Add the object to it's parent children. Note that we don't set parent's
			// temporary key - if the parent is still unknown, it may be the root object,
			// however if we find it as a child of another object later on, we'll set it's
			// temporary key at that point (see above).
			NSMutableDictionary* parentChildren = [parentHierarchyData objectForKey:kTKDataHierarchyChildrenKey];
			[parentChildren setObject:objectHierarchyData forKey:objectName];
		}
	}	
	
	// Create the default markup. Then handle all root level objects. This in turn will
	// handle their children and these their and so on in the recursive method. Note that
	// all root level nodes with temporary flag set, should not be handled. These will
	// eventually be removed from the database root level, at the end of the clean XML
	// generation. However for the moment they are left here, so that code generation
	// is simpler - to find an object and it's hierarchy, simply search for it in the
	// root...
	NSXMLDocument* document = [[NSXMLDocument alloc] init];
	NSXMLElement* projectElement = [NSXMLElement elementWithName:@"project"];
	[projectElement addAttribute:[NSXMLNode attributeWithName:@"generator" stringValue:cmd.generator]];
	[document setVersion:@"1.0"];
	[document addChild:projectElement];
	NSArray* sortedObjects = [[hierarchies allKeys] sortedArrayUsingSelector:@selector(compare:)];
	for (NSString* objectName in sortedObjects)
	{
		NSDictionary* objectData = [hierarchies objectForKey:objectName];
		NSNumber* temporaryFlag = [objectData objectForKey:kTKDataHierarchyTempKey];
		if (!temporaryFlag || ![temporaryFlag boolValue])
		{
			[self createHierarchyDataForObject:objectData withinNode:projectElement];
		}
	}
	
	// Store the cleaned markup to the application data.
	[database setObject:document forKey:kTKDataMainHierarchyKey];
	
	// Save the markup.
	NSError* error = nil;
	NSData* markupData = [document XMLDataWithOptions:NSXMLNodePrettyPrint];
	[document release];
	NSString* filename = [self outputBasePath];
	filename = [filename stringByAppendingPathComponent:[self outputHierarchyFilename]];
	if (![markupData writeToFile:filename options:0 error:&error])
	{
		logError(@"Failed writting clean Hierarchy.xml to '%@'!", filename);
		[Systemator throwExceptionWithName:kTKConverterException basedOnError:error];
	}
	
	[loopAutoreleasePool drain];
	logInfo(@"Finished creating clean hierarchy documentation file.");
}

//----------------------------------------------------------------------------------------
- (void) fixCleanObjectDocumentation
{
	logNormal(@"Fixing clean objects documentation links...");
	
	// Prepare common variables to optimize loop a bit.
	NSAutoreleasePool* loopAutoreleasePool = nil;
	
	// Handle all files in the database.
	NSDictionary* objects = [database objectForKey:kTKDataMainObjectsKey];
	for (NSString* objectName in objects)
	{
		// Setup the autorelease pool for this iteration. Note that we are releasing the
		// previous iteration pool here as well. This is because we use continue to 
		// skip certain iterations, so releasing at the end of the loop would not work...
		// Also note that after the loop ends, we are releasing the last iteration loop.
		[loopAutoreleasePool drain];
		loopAutoreleasePool = [[NSAutoreleasePool alloc] init];
		
		// Get the required object data.
		NSMutableDictionary* objectData = [objects objectForKey:objectName];
		logVerbose(@"- Handling '%@'...", objectName);
		
		[self fixInheritanceForObject:objectName objectData:objectData objects:objects];
		[self fixLocationForObject:objectName objectData:objectData objects:objects];
		[self fixReferencesForObject:objectName objectData:objectData objects:objects];
		[self fixParaLinksForObject:objectName objectData:objectData objects:objects];
		[self fixEmptyParaForObject:objectName objectData:objectData objects:objects];
	}
	
	// When all fixes are applied, we can remove temporary objects from the hierarchies
	// root level. The outside code relies on the fact that the hierarchies is "clean"
	// and only contains objects on the places where they belong.
	NSMutableDictionary* hierarchies = [database objectForKey:kTKDataMainHierarchiesKey];
	for (int i = 0; i < [hierarchies count]; i++)
	{
		NSString* objectName = [[hierarchies allKeys] objectAtIndex:i];
		NSDictionary* data = [hierarchies objectForKey:objectName];
		NSNumber* temporary = [data objectForKey:kTKDataHierarchyTempKey];
		if (temporary && [temporary boolValue])
		{
			logDebug(@"  - Removing temporary object '%@' from root...", objectName);
			[hierarchies removeObjectForKey:objectName];
			i--;
		}
	}
	
	// Release last iteration pool.
	[loopAutoreleasePool drain];
	logInfo(@"Finished fixing clean objects documentation links.");
}

//----------------------------------------------------------------------------------------
- (void) saveCleanObjectDocumentationFiles
{
	logNormal(@"Saving clean object documentation files...");
	
	// Save all objects.
	NSDictionary* objects = [database objectForKey:kTKDataMainObjectsKey];
	for (NSString* objectName in objects)
	{
		NSAutoreleasePool* loopAutoreleasePool = [[NSAutoreleasePool alloc] init];		
		NSDictionary* objectData = [objects objectForKey:objectName];
		
		// Prepare the file name.
		NSString* filename = [self outputBasePath];
		filename = [filename stringByAppendingPathComponent:[self outputObjectFilenameForObject:objectData]];
		
		// Save the document.
		logVerbose(@"- Saving '%@' to '%@'...", objectName, filename);
		NSXMLDocument* document = [objectData objectForKey:kTKDataObjectMarkupKey];
		NSData* documentData = [document XMLDataWithOptions:NSXMLNodePrettyPrint];
		if (![documentData writeToFile:filename atomically:NO])
		{
			logError(@"Failed saving '%@' to '%@'!", objectName, filename);
		}
		
		[loopAutoreleasePool drain];
	}
	
	logInfo(@"Finished saving clean object documentation files...");
}

//////////////////////////////////////////////////////////////////////////////////////////
#pragma mark Clean XML "makeup" handling
//////////////////////////////////////////////////////////////////////////////////////////

//----------------------------------------------------------------------------------------
- (void) createMembersDataForObject:(NSString*) objectName
						 objectData:(NSMutableDictionary*) objectData
{
	// Add the empty dictionary to the object data.
	NSMutableDictionary* members = [NSMutableDictionary dictionary];
	[objectData setObject:members forKey:kTKDataObjectMembersKey];
	
	// Get the array of all member nodes.
	NSXMLDocument* document = [objectData objectForKey:kTKDataObjectMarkupKey];
	NSArray* memberNodes = [document nodesForXPath:@"object/sections/section/member" error:nil];
	for (NSXMLElement* memberNode in memberNodes)
	{
		NSXMLNode* kindAttr = [memberNode attributeForName:@"kind"];
		if (kindAttr)
		{
			NSArray* nameNodes = [memberNode nodesForXPath:@"name" error:nil];
			if ([nameNodes count] > 0)
			{
				// Get member data.
				NSString* memberName = [[nameNodes objectAtIndex:0] stringValue];
				NSString* memberKind = [kindAttr stringValue];
				
				// Prepare member prefix.
				NSString* memberPrefix = @"";
				if ([memberKind isEqualToString:@"class-method"])
					memberPrefix = @"+";
				else if ([memberKind isEqualToString:@"instance-method"])
					memberPrefix = @"-";
				
				// Prepare member selector. Note that we use the template to allow the
				// users specify their desired format. If prefix is used, we should use
				// the template, otherwise we stick to the name only. This avoids the
				// empty spaces in front of properties for example.
				NSString* memberSelector = nil;
				if ([memberPrefix length] > 0)
				{
					memberSelector = cmd.memberReferenceTemplate;
					memberSelector = [memberSelector stringByReplacingOccurrencesOfString:@"$PREFIX" withString:memberPrefix];
					memberSelector = [memberSelector stringByReplacingOccurrencesOfString:@"$MEMBER" withString:memberName];
				}
				else
				{
					memberSelector = memberName;
				}
				logDebug(@"  - Generating '%@' member data...", memberSelector);
				
				// Create member data dictionary.
				NSMutableDictionary* memberData = [NSMutableDictionary dictionary];
				[memberData setObject:memberName forKey:kTKDataMemberNameKey];
				[memberData setObject:memberPrefix forKey:kTKDataMemberPrefixKey];
				[memberData setObject:memberSelector forKey:kTKDataMemberSelectorKey];
				
				// Add the dictionary to the members data.
				[members setObject:memberData forKey:memberName];
				
				// Add the member selector to the XML.
				NSXMLElement* selectorNode = [NSXMLNode elementWithName:@"selector" stringValue:memberSelector];
				[memberNode addChild:selectorNode];
			}
		}
	}
}

//----------------------------------------------------------------------------------------
- (void) createHierarchyDataForObject:(NSDictionary*) objectHierarchyData
						   withinNode:(NSXMLElement*) node
{
	// Get the object data.
	NSDictionary* objectData = [objectHierarchyData objectForKey:kTKDataHierarchyObjectDataKey];
	NSDictionary* children = [objectHierarchyData objectForKey:kTKDataHierarchyChildrenKey];	
	NSString* objectName = [objectHierarchyData objectForKey:kTKDataHierarchyObjectNameKey];
	NSString* objectKind = [objectData objectForKey:kTKDataObjectKindKey];
	NSString* objectRef = [objectData valueForKey:kTKDataObjectRelPathKey];
	if (!objectKind) objectKind = @"class";
	logVerbose(@"- Handling '%@'...", objectName);
	
	// Create the node that will represent the object itself.
	NSXMLElement* objectNode = [NSXMLNode elementWithName:@"object"];
	[objectNode addAttribute:[NSXMLNode attributeWithName:@"kind" stringValue:objectKind]];
	if (objectRef) [objectNode addAttribute:[NSXMLNode attributeWithName:@"id" stringValue:objectRef]];
	[node addChild:objectNode];
	
	// Create the name subnode.
	NSXMLElement* nameNode = [NSXMLNode elementWithName:@"name" stringValue:objectName];
	[objectNode addChild:nameNode];
	
	// If there are any children, process them. First create the children node, then
	// add all children to it.
	if ([children count] > 0)
	{
		NSXMLElement* childrenNode = [NSXMLNode elementWithName:@"children"];
		[objectNode addChild:childrenNode];
		
		NSArray* sortedChildrenNames = [[children allKeys] sortedArrayUsingSelector:@selector(compare:)];
		for (NSString* childName in sortedChildrenNames)
		{
			NSDictionary* childData = [children objectForKey:childName];
			[self createHierarchyDataForObject:childData 
									withinNode:childrenNode];
		}
	}
}

//----------------------------------------------------------------------------------------
- (void) fixInheritanceForObject:(NSString*) objectName
					  objectData:(NSMutableDictionary*) objectData
						 objects:(NSDictionary*) objects
{
	NSCharacterSet* whitespaceSet = [NSCharacterSet whitespaceCharacterSet];
	
	// Fix the base class link. If the base class is one of the known objects,
	// add the id attribute so we can link to it when creating xhtml. Note that
	// we need to handle protocols here too - if a class conforms to protocols,
	// we should change the name of the node from <base> to <conforms> so that we
	// have easier job while generating html. We should also create the link to
	// the known protocols.
	NSXMLDocument* cleanDocument = [objectData objectForKey:kTKDataObjectMarkupKey];
	NSArray* baseNodes = [cleanDocument nodesForXPath:@"/object/base" error:nil];
	for (NSXMLElement* baseNode in baseNodes)
	{
		NSString* refValue = [baseNode stringValue];
		if ([objects objectForKey:refValue])
		{
			NSString* linkReference = [self objectReferenceFromObject:objectName toObject:refValue];
			NSXMLNode* idAttribute = [NSXMLNode attributeWithName:@"id" stringValue:linkReference];
			[baseNode addAttribute:idAttribute];
			logDebug(@"  - Found base class reference to '%@' at '%@'.", refValue, linkReference);
		}
		else
		{
			refValue = [refValue stringByTrimmingCharactersInSet:whitespaceSet];
			if ([refValue hasPrefix:@"<"] && [refValue hasSuffix:@">"])
			{					
				NSRange protocolNameRange = NSMakeRange(1, [refValue length] - 2);
				refValue = [refValue substringWithRange:protocolNameRange];
				refValue = [refValue stringByTrimmingCharactersInSet:whitespaceSet];
				
				NSXMLElement* protocolNode = [NSXMLNode elementWithName:@"protocol"];
				[protocolNode setStringValue:refValue];
				
				if ([objects objectForKey:refValue])
				{
					NSString* linkReference = [self objectReferenceFromObject:objectName toObject:refValue];
					NSXMLNode* idAttribute = [NSXMLNode attributeWithName:@"id" stringValue:linkReference];
					[protocolNode addAttribute:idAttribute];
					logDebug(@"  - Found protocol reference to '%@' at '%@'.", refValue, linkReference);
				}
				else
				{
					logDebug(@"  - Found protocol reference to '%@'.", refValue);
				}
				
				NSUInteger index = [baseNode index];
				NSXMLElement* parentNode = (NSXMLElement*)[baseNode parent];
				[parentNode replaceChildAtIndex:index withNode:protocolNode];
			}
		}
	}
	
	// Now prepare the object full hierarchy. This will add additional <base> nodes after
	// the main one for classes which have "deep" inheritance. All known bases will also
	// be documented. Note that we only handle objects that are contained in the hierarchy.
	// Also note that we need to fetch base nodes again (we should only have one now, 
	// however we play safe and start adding after the last one).
	NSString* parentName = [objectData objectForKey:kTKDataObjectParentKey];
	if (parentName)
	{
		// We need the object node in case there's non base node - then we should just
		// add additional base nodes directly to the object node.
		NSArray* objectNodes = [cleanDocument nodesForXPath:@"object" error:nil];
		NSXMLElement* objectNode = [objectNodes lastObject];
		
		// Prepare default insertion index. If object node contains less than 4 subnodes
		// (name, file, base), we should insert to the end, otherwise we should insert
		// after the third (after the base node). However, if the node contains base
		// subnodes, we will properly setup the insertion index after the last one.
		NSUInteger insertionIndex = ([objectNode childCount] < 4) ? [objectNode childCount] - 1 : 3;
		NSArray* baseNodes = [objectNode nodesForXPath:@"base" error:nil];
		if ([baseNodes count] > 0)
		{
			insertionIndex = [[baseNodes lastObject] index] + 1;
		}

		// Note that this loop will skip the immediate object's parent since this one is
		// already documented. However to avoid code repetition, this is not handled
		// outside, and therefore requires a conditional within the loop.
		int parentLevel = 0;
		while (parentName)
		{
			// Only handle second level inheritance...
			NSDictionary* parentData = [objects objectForKey:parentName];
			if (parentLevel > 0)
			{
				NSXMLElement* baseNode = [NSXMLNode elementWithName:@"base" stringValue:parentName];
				if (parentData)
				{
					NSString* linkReference = [self objectReferenceFromObject:objectName toObject:parentName];
					NSXMLNode* idAttribute = [NSXMLNode attributeWithName:@"id" stringValue:linkReference];
					[baseNode addAttribute:idAttribute];
				}
				[objectNode insertChild:baseNode atIndex:insertionIndex];
				insertionIndex++;
			}
			
			// Continue with the next parent.
			parentName = [parentData objectForKey:kTKDataObjectParentKey];
			parentLevel++;
		}
	}
}

//----------------------------------------------------------------------------------------
- (void) fixLocationForObject:(NSString*) objectName
				   objectData:(NSMutableDictionary*) objectData
					  objects:(NSDictionary*) objects
{
	// We only need to check this for classes and only if this is enabled.
	if (cmd.fixClassLocations && [[objectData objectForKey:kTKDataObjectKindKey] isEqualToString:@"class"])
	{
		NSXMLDocument* cleanDocument = [objectData objectForKey:kTKDataObjectMarkupKey];
		NSArray* fileNodes = [cleanDocument nodesForXPath:@"object/file" error:nil];
		if ([fileNodes count] > 0)
		{
			for (NSXMLElement* fileNode in fileNodes)
			{
				// If path extension is not .h, check further.
				NSString* path = [fileNode stringValue];
				NSString* extension = [path pathExtension];
				if ([extension isEqualToString:@"m"] ||
					[extension isEqualToString:@"mm"])
				{
					// If the path contains other parts, besides extension and file name,
					// or it doesn't start with the object name, replace it...
					if (![path hasPrefix:objectName] ||
						[path length] != [extension length] + [objectName length] + 1)
					{
						NSString* newPath = [NSString stringWithFormat:@"%@.h", objectName];
						logDebug(@"  - Fixing strange looking class file '%@' to '%@'...",
								 path,
								 newPath);
						[fileNode setStringValue:newPath];
					}
				}
			}
		}
	}
}

//----------------------------------------------------------------------------------------
- (void) fixReferencesForObject:(NSString*) objectName
					 objectData:(NSMutableDictionary*) objectData
						objects:(NSDictionary*) objects
{
	NSCharacterSet* whitespaceSet = [NSCharacterSet whitespaceCharacterSet];
	NSCharacterSet* classStartSet = [NSCharacterSet characterSetWithCharactersInString:@"("];
	NSCharacterSet* classEndSet = [NSCharacterSet characterSetWithCharactersInString:@")"];
	NSCharacterSet* invalidSet = [NSCharacterSet characterSetWithCharactersInString:@" -+"];
	
	// Now look for all <ref> nodes. Then determine the type of link from the link
	// text. The link can either be internal, within the same object or it can be
	// to a member of another object.
	NSXMLDocument* cleanDocument = [objectData objectForKey:kTKDataObjectMarkupKey];
	NSArray* refNodes = [cleanDocument nodesForXPath:@"//ref" error:nil];
	for (NSXMLElement* refNode in refNodes)
	{
		// Get the reference (link) object and member components. The links from
		// doxygen have the format "memberName (ClassName)". The member name includes
		// all the required objective-c colons for methods. Note that some links may 
		// only contain member and some only object components! The links that only
		// contain object component don't encapsulate the object name within the
		// parenthesis! However these are all links to the current object, so we can
		// easily determine the type by comparing to the current object name.
		NSString* refValue = [refNode stringValue];
		if ([refValue length] > 0)
		{
			NSString* refObject = nil;
			NSString* refMember = nil;
			NSScanner* scanner = [NSScanner scannerWithString:refValue];
			
			// If we cannot parse the value of the tag, write the error and continue
			// with next one. Although this should not really happen since we only
			// come here if some text is found, it's still nice to obey the framework...
			if (![scanner scanUpToCharactersFromSet:classStartSet intoString:&refMember])
			{
				logNormal(@"Skipping reference '%@' for object '%@' because tag value was invalid!",
						  refValue,
						  refMember);
				continue;
			}
			refMember = [refMember stringByTrimmingCharactersInSet:whitespaceSet];
			
			// Find and parse the object name part if it exists. Note that we need to be
			// able to handle categories here which should include the ending parenthesis.
			// This is stripped out by the scanner.
			if ([scanner scanCharactersFromSet:classStartSet intoString:NULL])
			{
				if ([scanner scanUpToCharactersFromSet:classEndSet intoString:&refObject])
				{
					refObject = [refObject stringByTrimmingCharactersInSet:whitespaceSet];
					if ([refValue hasSuffix:@"))"]) refObject = [refObject stringByAppendingString:@")"];
				}
			}
			
			// Doxygen appends -p to the end of the protocol names, so we should remove
			// that before checking any further. Note that this apparently happens only
			// for links to protocol members, so we can only test if both components
			// are provided.
			if (refMember && refObject && [refObject hasSuffix:@"-p"])
			{
				logDebug(@"  - Found broken '%@' protocol link...", refObject);
				refObject = [refObject substringToIndex:[refObject length] - 2];
			}
			
			// If we only have one component, we should first determine if it
			// represents an object name or member name. In the second case, the
			// reference is alredy setup properly. In the first case, however, we
			// need to swap the object and member reference.
			if (!refObject && [objects objectForKey:refMember])
			{
				refObject = refMember;
				refMember = nil;
			}
			
			// If the link represents a reference to a merged category, we should change
			// the reference object to the main class.
			if (cmd.mergeKnownCategoriesToClasses &&
				[refObject hasSuffix:@")"] && 
				[refObject hasPrefix:objectName])
			{
				refObject = objectName;
			}
		
			// If we have both components and the object part points to current
			// object, we should discard it and only use member component.
			if (refObject && refMember && [refObject isEqualToString:objectName])
			{
				refObject = nil;
			}
			
			// Validate member reference.
			if (refMember)
			{
				refMember = [refMember stringByTrimmingCharactersInSet:invalidSet];
			}
			
			// Prepare the reference description. Again it depends on the components
			// of the reference value. If both components are present, we should
			// combine them. Otherwise just use the one that is available. Note that
			// in case this is inter-file link we should check if we need to link to
			// another sub-directory.
			NSString* linkDescription = nil;
			NSString* linkReference = nil;
			if (refObject && refMember)
			{
				linkDescription = [self objectLinkNameForObject:refObject andMember:refMember];
				linkReference = [NSString stringWithFormat:@"#%@", refMember];
			}
			else if (refObject)
			{
				linkDescription = refObject;
				linkReference = @"";
			}
			else
			{
				linkDescription = [self memberLinkNameForObject:objectName andMember:refMember];
				linkReference = [NSString stringWithFormat:@"#%@", refMember];
			}
			
			// Check if we need to link to another directory.
			if (refObject && ![refObject isEqualToString:objectName])
			{
				NSString* linkPath = [self objectReferenceFromObject:objectName toObject:refObject];
				linkReference = [NSString stringWithFormat:@"%@%@", linkPath, linkReference];
			}
			
			// Update the <ref> tag. First we need to remove any existing id
			// attribute otherwise the new one will not be used. Then we need to
			// replace the value with the new description.
			NSXMLNode* idAttribute = [NSXMLNode attributeWithName:@"id" stringValue:linkReference];
			[refNode removeAttributeForName:@"id"];
			[refNode addAttribute:idAttribute];
			[refNode setStringValue:linkDescription];
			logDebug(@"  - Found reference to %@ at '%@'.", linkDescription, linkReference);
		}
	}
}

//----------------------------------------------------------------------------------------
- (void) fixParaLinksForObject:(NSString*) objectName
					objectData:(NSMutableDictionary*) objectData
					   objects:(NSDictionary*) objects
{
	// The handling of replacements is done in two phases. First we scan all possible
	// documentation words and prepare the list of words which should be replaced and
	// the corresponding replacement strings. This is held in the replacements dictionary.
	// However in some cases we may have a word which contains another, smaller word
	// within. So we need do first replace the larger word and only then the smaller one.
	// But even this doesn't handle all cases, so we first obsfucate certain replacements
	// which can potentially contain words from other replacements so we obsfucate those
	// and when all are replaced, we run through all obsfucations as well... If we could
	// find a better way of replacing words at the moment of detection, we could avoid
	// all this hassle, but for the moment, we'll have to live with it.
	NSCharacterSet* whitespaceSet = [NSCharacterSet whitespaceCharacterSet];
	NSMutableDictionary* replacements = [NSMutableDictionary dictionary];
	NSMutableDictionary* obsfucations = [NSMutableDictionary dictionary];
	
	// Get given object members. This is used for testing links to the members of the
	// same object.
	NSDictionary* objectMembers = [objectData objectForKey:kTKDataObjectMembersKey];
	
	// We also need to handle broken doxygen member links handling. This is especially
	// evident in categories where the links to member functions are not properly
	// handled at all. At the moment we only handle members which are expressed either
	// as ::<membername> or <membername>() notation. Since doxygen skips these, and
	// leaves the format as it was written in the original documentation, we can
	// easily find them in the source text without worrying about breaking the links
	// we fixed in the above loop.
	NSXMLDocument* cleanDocument = [objectData objectForKey:kTKDataObjectMarkupKey];
	NSArray* textNodes = [cleanDocument nodesForXPath:@"//para/text()|//para/*/text()" error:nil];
	for (NSXMLNode* textNode in textNodes)
	{
		// Scan the text word by word and check the words for possible member links.
		// For each detected member link, add the original and replacement text to
		// the replacements dictionary. We'll use it later on to replace all occurences
		// of the text node string and then replace the whole text node string value.
		NSString* word = nil;			
		NSScanner* scanner = [NSScanner scannerWithString:[textNode stringValue]];
		while ([scanner scanUpToCharactersFromSet:whitespaceSet intoString:&word])
		{
			// Fix members that are declared with two colons. Skip words which are composed
			// from double colons only so that users can still use that in documentation.
			if ([word hasPrefix:@"::"] && [word length] > 2 && ![replacements objectForKey:word])
			{
				NSString* member = [word substringFromIndex:2];
				NSString* name = [self memberLinkNameForObject:objectName andMember:member];
				NSString* link = nil;
				if ([objectMembers objectForKey:member])
				{
					link = [NSString stringWithFormat:@"<ref id=\"#%@\">%@</ref>", member, name];
					logDebug(@"  - Found reference to %@ at '#%@'.", member, member);
				}
				else
				{
					link = name;
					logError(@"- Found reference to unknown member %@!", member);
				}
				[replacements setObject:link forKey:word];
			}
			
			// Fix members that are declated with parenthesis. Skip words which are composed
			// from parenthesis only so that users can still use that in documentation. Note
			// that this is also where we come in case a category member link is desired.
			// For example: for documentation "NSObject(Logging)::logger()", doxygen would
			// convert to "NSObject(Logging)logger()". So we need to check whether the given
			// word contains parenthesis in the middle and assume this is a category member
			// link if so. Note that class members are correctly handled by doxygen, so
			// we don't need to handle these cases.
			if ([word hasSuffix:@"()"] && [word length] > 2 && ![replacements objectForKey:word])
			{
				// Does the word include parenthesis in the middle? If so, this is link to
				// a category member and we should handle it differently because it
				// represents link to member of a category. We should check if the category
				// is known or not and prepare the link in the first case and only prettier
				// name in second. Note that we need to obsfucate the replacement since
				// a category object link may also be present and it will partially
				// replace these!
				NSUInteger firstOpenParLocation = [word rangeOfString:@"("].location;
				NSUInteger firstCloseParLocation = [word rangeOfString:@")"].location;
				if (firstOpenParLocation < [word length] - 2 &&
					firstCloseParLocation < [word length] - 1)
				{
					NSString* category = [word substringToIndex:firstCloseParLocation + 1];
					NSString* member = [word substringFromIndex:firstCloseParLocation + 1];
					member = [member substringToIndex:[member length] - 2];
					NSString* name = [self objectLinkNameForObject:category andMember:member];
					NSDictionary* categoryData = [objects objectForKey:category];
					if (categoryData)
					{
						NSString* categoryLink = [self objectReferenceFromObject:objectName toObject:category];
						NSString* link = [NSString stringWithFormat:@"<ref id=\"%@#%@\">%@</ref>", 
										  categoryLink, 
										  member,
										  name];
						NSString* obsfucated = [self obsfucatedStringFromString:link];
						[obsfucations setObject:link forKey:obsfucated];
						[replacements setObject:obsfucated forKey:word];
						logDebug(@"  - Found reference to member %@ from category %@.", member, category);
					}
					else
					{
						NSString* obsfucated = [self obsfucatedStringFromString:name];
						[obsfucations setObject:name forKey:obsfucated];
						[replacements setObject:obsfucated forKey:word];
						logDebug(@"  - Found reference to member %@ from unknown category %@.", member, category);
					}
				}

				// This is either true member link, protocol link or unknown class link.
				else
				{
					// Does the work contain :: in the middle? If so, this is a link to a
					// protocol or unknown class member, so we need to handle it similar to 
					// categories above.
					NSRange colonsRange = [word rangeOfString:@"::"];
					if (colonsRange.location != NSNotFound)
					{
						NSString* class = [word substringToIndex:colonsRange.location];
						NSString* member = [word substringFromIndex:colonsRange.location + 2];
						member = [member substringToIndex:[member length] - 2];
						NSString* name = [self objectLinkNameForObject:class andMember:member];
						NSDictionary* linkData = [objects objectForKey:class];
						if (linkData)
						{
							NSString* classLink = [self objectReferenceFromObject:objectName toObject:class];
							NSString* link = [NSString stringWithFormat:@"<ref id=\"%@#%@\">%@</ref>", 
											  classLink, 
											  member,
											  name];
							NSString* obsfucated = [self obsfucatedStringFromString:link];
							[obsfucations setObject:link forKey:obsfucated];
							[replacements setObject:obsfucated forKey:word];
							logDebug(@"  - Found reference to member %@ from object %@.", member, class);
						}
						else
						{
							[replacements setObject:name forKey:word];
							logDebug(@"  - Found reference to %@ from unknown class %@.", member, class);
						}
					}
					else
					{
						NSString* member = [word substringToIndex:[word length] - 2];
						NSString* name = [self memberLinkNameForObject:objectName andMember:member];
						NSString* link = nil;
						if ([objectMembers objectForKey:member])
						{
							link = [NSString stringWithFormat:@"<ref id=\"#%@\">%@</ref>", member, name];
							logDebug(@"  - Found reference to %@ at '#%@'.", member, member);
						}
						else
						{
							link = name;
							logError(@"- Found reference to unknown member %@!", member);
						}
						[replacements setObject:link forKey:word];
					}
				}
			}
			
			// Fix known category links.
			NSDictionary* linkedObjectData = [objects objectForKey:word];
			if (linkedObjectData && [[linkedObjectData objectForKey:kTKDataObjectKindKey] isEqualToString:@"category"])
			{
				NSString* link = [self objectReferenceFromObject:objectName toObject:word];
				NSString* linkReference = [NSString stringWithFormat:@"<ref id=\"%@\">%@</ref>", link, word];
				[replacements setObject:linkReference forKey:word];
				logDebug(@"  - Found reference to %@ at '%@'.", word, link);
			}
		}			
	}
	
	// Fix member links within the see also section. We should add the reference for each
	// item which doesn't contain the <ref> tag already. This happens for all references
	// to other classes or categories for which doxygen cannot find the target. Note that
	// we need to add the parenthesis (or any other unique identifier) to these items,
	// since replacing method names will also replace all valid <ref>s which will result
	// in exceptions when parsing the updated XML later on. This is especially important
	// when fixing inter-file links.
	NSArray* testNodes = [cleanDocument nodesForXPath:@"//seeAlso/item" error:nil];
	for (NSXMLNode* testNode in testNodes)
	{
		if ([[testNode nodesForXPath:@"ref" error:nil] count] == 0)
		{
			NSString* itemValue = [[testNode stringValue] stringByTrimmingCharactersInSet:whitespaceSet];
			NSString* name = [self memberLinkNameForObject:objectName andMember:itemValue];
			NSString* link = [NSString stringWithFormat:@"<ref id=\"#%@\">%@</ref>", itemValue, name];
			NSString* fixedValue = [itemValue stringByAppendingString:@"()"];
			[replacements setObject:link forKey:fixedValue];
			[testNode setStringValue:fixedValue];
			logDebug(@"  - Found broken see also reference to '%@'.", itemValue);
		}
	}
		
	// We should replace all found references with correct ones. Note that we
	// must also wrap the replaced string within the <ref> tag. So for example
	// instead of 'work()' we would end with '<ref id="#work">work</ref>'. In order
	// for this to work, we have to export the whole XML, replace all occurences and
	// then re-import the new XML. If we would change text nodes directly, the <ref>
	// tags would be imported as &lt; and similar...
	if ([replacements count] > 0)
	{
		NSString* xmlString = [cleanDocument XMLString];
		
		// Replace all occurences of the found member links with the fixed notation. Note
		// that we have to replace by using sorted keys by their names to make sure we
		// handle larger names first. Note that we need to scan throught
		NSArray* sortedWords = [[replacements allKeys] sortedArrayUsingSelector:@selector(compare:)];
		for (NSString* word in [sortedWords reverseObjectEnumerator])
		{
			NSString* replacement = [replacements objectForKey:word];
			xmlString = [xmlString stringByReplacingOccurrencesOfString:word withString:replacement];
		}
		
		// Now re-apply all obsfucations.
		for (NSString* word in obsfucations)
		{
			NSString* replacement = [obsfucations objectForKey:word];
			xmlString = [xmlString stringByReplacingOccurrencesOfString:word withString:replacement];
		}
		
		// Reload the XML from the updated string and replace the old one in the
		// object data. A bit inefficient, but works...
		NSError* error = nil;
		cleanDocument = [[NSXMLDocument alloc] initWithXMLString:xmlString 
														 options:0 
														   error:&error];
		if (!cleanDocument)
		{
			logError(@"Failed reloading clean XML document!");
			[Systemator throwExceptionWithName:kTKConverterException basedOnError:error];
		}
		[objectData setObject:cleanDocument forKey:kTKDataObjectMarkupKey];
		[cleanDocument release];
	}		
}

//----------------------------------------------------------------------------------------
- (void) fixEmptyParaForObject:(NSString*) objectName
					objectData:(NSMutableDictionary*) objectData
					   objects:(NSDictionary*) objects
{
	if (cmd.removeEmptyParagraphs)
	{
		// Note that 0xFFFC chars are added during clean XML xstl phase, so these have to be
		// removed too - if the paragraph only contains those, we should delete it... Why
		// this happens I don't know, but this fixes it (instead of only deleting the 0xFFFC
		// we are deleting the last 16 unicode chars). If this creates problems in other
		// languages, we should make this code optional.
		NSCharacterSet* whitespaceSet = [NSCharacterSet whitespaceCharacterSet];
		NSCharacterSet* customSet = [NSCharacterSet characterSetWithRange:NSMakeRange(0xFFF0, 16)];
		
		// Find all paragraphs that only contain empty text and remove them. This will result
		// in better looking documentation. Although these are left because spaces or such
		// were used in the documentation, in most cases they are not desired. For example,
		// Xcode automatically appends a space for each empty documentation line in my style
		// of documenting; since I don't want to deal with this, I will fix it after the
		// documentation has been created.	
		NSXMLDocument* cleanDocument = [objectData objectForKey:kTKDataObjectMarkupKey];
		NSArray* paraNodes = [cleanDocument nodesForXPath:@"//para" error:nil];
		for (NSXMLElement* paraNode in paraNodes)
		{
			NSString* paragraph = [paraNode stringValue];
			paragraph = [paragraph stringByTrimmingCharactersInSet:whitespaceSet];
			paragraph = [paragraph stringByTrimmingCharactersInSet:customSet];
			if ([paraNode childCount] == 0 || [paragraph length] == 0)
			{
				NSXMLElement* parent = (NSXMLElement*)[paraNode parent];
				logDebug(@"  - Removing empty paragraph...");
				[parent removeChildAtIndex:[paraNode index]];
			}
		}		
	}
}

//////////////////////////////////////////////////////////////////////////////////////////
#pragma mark Helper methods
//////////////////////////////////////////////////////////////////////////////////////////

//----------------------------------------------------------------------------------------
- (NSDictionary*) linkDataForObject:(NSString*) objectName
						  andMember:(NSString*) memberName
{
	NSDictionary* objects = [database objectForKey:kTKDataMainObjectsKey];
	NSDictionary* objectData = [objects objectForKey:objectName];
	if (objectData)
	{
		NSDictionary* membersData = [objectData objectForKey:kTKDataObjectMembersKey];
		return [membersData objectForKey:memberName];
	}
	return nil;
}

//----------------------------------------------------------------------------------------
- (NSString*) objectLinkNameForObject:(NSString*) objectName
							andMember:(NSString*) memberName
{
	NSString* prefix = @"";
	NSDictionary* memberData = [self linkDataForObject:objectName andMember:memberName];
	if (memberData) prefix = [memberData objectForKey:kTKDataMemberPrefixKey];
	
	NSString* result = cmd.objectReferenceTemplate;
	result = [result stringByReplacingOccurrencesOfString:@"$PREFIX" withString:prefix];
	result = [result stringByReplacingOccurrencesOfString:@"$OBJECT" withString:objectName];
	result = [result stringByReplacingOccurrencesOfString:@"$MEMBER" withString:memberName];
	return result;
}

//----------------------------------------------------------------------------------------
- (NSString*) memberLinkNameForObject:(NSString*) objectName
							andMember:(NSString*) memberName
{
	NSDictionary* memberData = [self linkDataForObject:objectName andMember:memberName];
	if (memberData) return [memberData objectForKey:kTKDataMemberSelectorKey];
	return memberName;
}

//----------------------------------------------------------------------------------------
- (NSString*) objectReferenceFromObject:(NSString*) source 
							   toObject:(NSString*) destination
{
	NSDictionary* objects = [database objectForKey:kTKDataMainObjectsKey];
	
	// Get the source and destination object's data.
	NSDictionary* sourceData = [objects objectForKey:source];
	NSDictionary* destinationData = [objects objectForKey:destination];
	
	// Get the source and destination object's sub directory.
	NSString* sourceSubdir = [sourceData objectForKey:kTKDataObjectRelDirectoryKey];
	NSString* destinationSubdir = [destinationData objectForKey:kTKDataObjectRelDirectoryKey];
	
	// If the two subdirectories are not the same, we should prepend the relative path.
	if (![sourceSubdir isEqualToString:destinationSubdir])
	{
		return [NSString stringWithFormat:
				@"../%@/%@%@",
				destinationSubdir, 
				destination, 
				kTKPlaceholderExtension];
	}
	
	return [NSString stringWithFormat:@"%@%@", destination, kTKPlaceholderExtension];
}

//----------------------------------------------------------------------------------------
- (NSString*) obsfucatedStringFromString:(NSString*) string
{
	NSMutableString* result = [NSMutableString string];
	for (int i = 0; i < [string length]; i++)
	{
		NSString* original = [string substringWithRange:NSMakeRange(i, 1)];
		[result appendString:original];
		[result appendString:@"*"];
	}
	return result;
}

//////////////////////////////////////////////////////////////////////////////////////////
#pragma mark Properties
//////////////////////////////////////////////////////////////////////////////////////////

@synthesize doxygenInfoProvider;

@end