From e6cf82be21a3cbb15915cb17b01c47de279b807c Mon Sep 17 00:00:00 2001
From: Tomaz Kragelj <tkragelj@gmail.com>
Date: Fri, 5 Jun 2009 21:31:32 +0200
Subject: [PATCH] Added support for browsing documentation set class hierarchy
 within the Xcode documentation window.

---
 DoxygenConverter+DocSet.h | 15 +++++++++++
 DoxygenConverter+DocSet.m | 56 +++++++++++++++++++++++++++++++++++++++
 DoxygenConverter.h        | 10 +++++--
 3 files changed, 79 insertions(+), 2 deletions(-)

diff --git a/DoxygenConverter+DocSet.h b/DoxygenConverter+DocSet.h
index 87deb9fb..48c37157 100644
--- a/DoxygenConverter+DocSet.h
+++ b/DoxygenConverter+DocSet.h
@@ -50,6 +50,7 @@ This message is automatically sent from @c DoxygenConverter::convert() in the pr
 @see createDocSetSourcePlistFile
 @see createDocSetTokesFile
 @see createDocSetBundle
+@see addDocSetNodeToElement:fromHierarchyData:
 */
 - (void) createDocSetNodesFile;
 
@@ -83,4 +84,18 @@ This message is automatically sent from @c DoxygenConverter::convert() in the pr
 */
 - (void) createDocSetBundle;
 
+/** Adds a new DocSet node as the child of the given parent element.
+
+The given hierarchy data contains the description of the node to add. The added node is
+either of the type folder if it contains children or it is a leaf otherwise. The methods
+will recursively add all subnodes as well.
+
+@param parent The Nodes.xml element to which to add new node.
+@param data The hierarchy object data that describes the node.
+@exception NSException Thrown if adding fails.
+@see createDocSetNodesFile
+*/
+- (void) addDocSetNodeToElement:(NSXMLElement*) parent
+			  fromHierarchyData:(NSDictionary*) data;
+
 @end
diff --git a/DoxygenConverter+DocSet.m b/DoxygenConverter+DocSet.m
index 718ba06e..8e08fa12 100644
--- a/DoxygenConverter+DocSet.m
+++ b/DoxygenConverter+DocSet.m
@@ -145,6 +145,25 @@ - (void) createDocSetNodesFile
 		}
 	}
 	
+	// At the end of the directories create class hierarchy.
+	NSXMLElement* hierarchyNodeElement = [NSXMLNode elementWithName:@"Node"];
+	[hierarchyNodeElement addAttribute:[NSXMLNode attributeWithName:@"type" stringValue:@"folder"]];
+	[indexSubnodesElement addChild:hierarchyNodeElement];
+	NSXMLElement* hierarchyNameElement = [NSXMLNode elementWithName:@"Name" stringValue:@"Class hierarchy"];
+	[hierarchyNodeElement addChild:hierarchyNameElement];
+	NSXMLElement* hierarchyPathElement = [NSXMLNode elementWithName:@"Path" stringValue:@"hierarchy.html"];
+	[hierarchyNodeElement addChild:hierarchyPathElement];
+	NSXMLElement* hierarchySubnodesElement = [NSXMLNode elementWithName:@"Subnodes"];
+	[hierarchyNodeElement addChild:hierarchySubnodesElement];
+	
+	// Scan for all classes in the hierarchy.
+	NSMutableDictionary* hierarchies = [database objectForKey:kTKDataMainHierarchiesKey];
+	for (NSString* objectName in hierarchies)
+	{
+		NSDictionary* hierarchyData = [hierarchies objectForKey:objectName];
+		[self addDocSetNodeToElement:hierarchySubnodesElement fromHierarchyData:hierarchyData];
+	}
+	
 	// Save the document.
 	NSError* error = nil;
 	NSString* filename = [cmd.outputDocSetResourcesPath stringByAppendingPathComponent:@"Nodes.xml"];
@@ -354,4 +373,41 @@ - (void) createDocSetBundle
 	logInfo(@"Finished creating DocSet bundle.");
 }
 
+//----------------------------------------------------------------------------------------
+- (void) addDocSetNodeToElement:(NSXMLElement*) parent
+			  fromHierarchyData:(NSDictionary*) data
+{
+	NSDictionary* children = [data objectForKey:kTKDataHierarchyChildrenKey];
+	NSDictionary* objectData = [data objectForKey:kTKDataHierarchyObjectDataKey];
+	NSString* objectName = [data objectForKey:kTKDataHierarchyObjectNameKey];
+	NSString* objectPath = [objectData objectForKey:kTKDataObjectRelPathKey];
+	if (!objectPath) objectPath = @"hierarchy.html";
+
+	// Create the main node that will represent the object.
+	NSXMLElement* node = [NSXMLNode elementWithName:@"Node"];
+	[parent addChild:node];
+	
+	// Create the name and path subnodes. Note that the path will be the main hierarchy
+	// index file if the node is not documented.
+	NSXMLElement* nameElement = [NSXMLNode elementWithName:@"Name" stringValue:objectName];
+	[node addChild:nameElement];
+	NSXMLElement* pathElement = [NSXMLNode elementWithName:@"Path" stringValue:objectPath];
+	[node addChild:pathElement];
+	
+	// If there are children, set the node type to folder and add subnodes.
+	if ([children count] > 0)
+	{
+		[node addAttribute:[NSXMLNode attributeWithName:@"type" stringValue:@"folder"]];
+		
+		NSXMLElement* subnodesElement = [NSXMLNode elementWithName:@"Subnodes"];
+		[node addChild:subnodesElement];
+		
+		for (NSString* childName in children)
+		{
+			NSDictionary* childHierarchyData = [children objectForKey:childName];
+			[self addDocSetNodeToElement:subnodesElement fromHierarchyData:childHierarchyData];
+		}
+	}
+}
+
 @end
diff --git a/DoxygenConverter.h b/DoxygenConverter.h
index e0324075..20db01ba 100644
--- a/DoxygenConverter.h
+++ b/DoxygenConverter.h
@@ -69,10 +69,16 @@ is a standard @c NSDictionary of the following layout:
   - @c "Hierarchy" key: contains a @c NSXMLDocument with clean hierarchy XML.
   - @c "Hierarchies" key: contains a @c NSMutableDictionary with classes hierarchy tree.
 	  - @c "<ObjectName>" key: contains a @c NSMutableDictionary describing the object:
+		  - @c "ObjectName" key: contains the object name. This is the same name as used
+			for the key in the parent dictionary. It still serves a purpose for the
+			non-documented objects which are part of the hierarchy - for there we can't
+			use the @c "ObjectData" key since we have no entry...
 		  - @c "ObjectData" key: contains a pointer to the object's data under the main
-			@c "Objects" key list.
+			@c "Objects" key list. Note that this is @c nil if the object is not
+			documented.
 		  - @c "Children" key: contains a @c NSMutableDictionary with all children of
-			this object. The dictionary has the same structure as the main @c "Hierarchy"
+			this object. If the object doesn't have any children, empty dictionary is
+			used. The dictionary has the same structure as the main @c "Hierarchies"
 			dictionary:
 			  - @c "<ObjectName>"...
 			  - ...