XMLOutputGenerator.h

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

#import "OutputGenerator.h"

//////////////////////////////////////////////////////////////////////////////////////////
//////////////////////////////////////////////////////////////////////////////////////////
/** Defines a concrete @c OutputGenerator which generates clean XML documentation.

The generator depends on @c DoxygenOutputGenerator output. It scans the doxygen XML
documentation and converts it to a cleaner XML which can be used for easier processing
by other generators. The generator also fixes member or inter-objects links and other
Objective-C specifics which are missed or not supported by doxygen.
*/
@interface XMLOutputGenerator : OutputGenerator
{
	id<OutputInfoProvider> doxygenInfoProvider;
}

//////////////////////////////////////////////////////////////////////////////////////////
/// @name Clean XML handling
//////////////////////////////////////////////////////////////////////////////////////////

/** Creates clean object XML markups.

This method scans the doxygen XML output. For each file it checks if it contains
a known object (by testing the file name) and that the file is documented. For each
known documented file, it adds the original markup in the form of the @c NSXMLParser
to the @c data dictionary. The key of the dictionary is the name of the described
object.
 
Note that this method doesn't save the clean XML file yet, it only prepares the
proper name including full path and adds all the data, including cleaned XML tree
into the database. Until the utility finishes working, it works on in-memory XML
representation and only save after all steps are finished.

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 convertion fails.
@see mergeCleanCategoriesToKnownObjects
@see updateCleanObjectsDatabase
@see createCleanIndexDocumentationFile
@see createCleanHierarchyDocumentationFile
@see fixCleanObjectDocumentation
@see saveCleanObjectDocumentationFiles
*/
- (void) createCleanObjectDocumentationMarkup;

/** Merges known object categories to their parent objects is desired.

The categories can either be merged into single sections, or their sections may be
preserved, based on the user command line options or global parameters.

@exception NSException Thrown if convertion fails.
@see createCleanObjectDocumentationMarkup
@see updateCleanObjectsDatabase
@see createCleanIndexDocumentationFile
@see createCleanHierarchyDocumentationFile
@see fixCleanObjectDocumentation
@see saveCleanObjectDocumentationFiles
*/
- (void) mergeCleanCategoriesToKnownObjects;

/** Updates clean objects XML database by integrating data dependent on the XML itself.

This message needs to be sent after @c mergeCleanCategoriesToKnownObjects() and
before @c fixCleanObjectDocumentation(). It handles the following:
- Creation of object members database entries.

@exception NSException Thrown if conversion fails.
@see createCleanObjectDocumentationMarkup
@see mergeCleanCategoriesToKnownObjects
@see createCleanIndexDocumentationFile
@see createCleanHierarchyDocumentationFile
@see fixCleanObjectDocumentation
@see saveCleanObjectDocumentationFiles
@see createMembersDataForObject:objectData:
*/
- (void) updateCleanObjectsDatabase;

/** Creates clean index XML file.

This method uses the data generated by the @c createCleanObjectDocumentationMarkup() and
creates the index file, so it is required that @c createCleanObjectDocumentationMarkup() 
is sent to the receiver before sending this message!

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 index file creation fails.
@see createCleanObjectDocumentationMarkup
@see mergeCleanCategoriesToKnownObjects
@see updateCleanObjectsDatabase
@see createCleanHierarchyDocumentationFile
@see createCleanHierarchyDocumentationFile
@see fixCleanObjectDocumentation
@see saveCleanObjectDocumentationFiles
*/
- (void) createCleanIndexDocumentationFile;

/** Creates clean hieararchy XML file.

This method uses the data generated by the @c createCleanObjectDocumentationMarkup() and
creates the hierarchy file, so it is required that @c createCleanObjectDocumentationMarkup() 
is sent to the receiver before sending this message!

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 index file creation fails.
@see createCleanObjectDocumentationMarkup
@see mergeCleanCategoriesToKnownObjects
@see updateCleanObjectsDatabase
@see createCleanIndexDocumentationFile
@see fixCleanObjectDocumentation
@see saveCleanObjectDocumentationFiles
@see createHierarchyDataForObject:withinNode:
*/
- (void) createCleanHierarchyDocumentationFile;

/** Fixes the clean object XML documentation.

This method will scan through all XML files generated in @c createCleanObjectDocumentationMarkup()
and will fix all things cannot be (easily) treated by the xslt. Note that this method
will not do any fixing or convertion itself. Instead it will scan through all documented
objects and will pass each one to the "child" methods that will do the actual work. The
methods that get called are:
- @c fixInheritanceForObject:objectData:objects:().
- @c fixReferencesForObject:objectData:objects:().
- @c fixParaLinksForObject:objectData:objects:().
- @c fixEmptyParaForObject:objectData:objects:().
 
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 fixing XML fails.
@see createCleanObjectDocumentationMarkup
@see mergeCleanCategoriesToKnownObjects
@see updateCleanObjectsDatabase
@see createCleanIndexDocumentationFile
@see createCleanHierarchyDocumentationFile
@see saveCleanObjectDocumentationFiles
*/
- (void) fixCleanObjectDocumentation;

/** Saved clean object XML markups to proper files.

This method will save all clean XML markups in the database to proper files.
 
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 saving fails.
@see createCleanObjectDocumentationMarkup
@see mergeCleanCategoriesToKnownObjects
@see updateCleanObjectsDatabase
@see createCleanIndexDocumentationFile
@see createCleanHierarchyDocumentationFile
@see fixCleanObjectDocumentation
*/
- (void) saveCleanObjectDocumentationFiles;

//////////////////////////////////////////////////////////////////////////////////////////
/// @name Clean XML "makeup" handling
//////////////////////////////////////////////////////////////////////////////////////////

/** Creates the members entry within the given object data.

This scans the actual object document and extracts all members data which is later used
when handling references. Note that this should be sent only after categories are merged
so that the correct data is used for generation.
 
This message is automatically sent from @c updateCleanObjectsDatabase for each documented
object and should not be sent otherwise. It is used to simplify otherwise large and
difficult to manage parent method.

@param objectName The name of the object for which we should create members.
@param objectData The data of the object into which to create the members.
@exception NSException Thrown if creation fails.
@see updateCleanObjectsDatabase
*/
- (void) createMembersDataForObject:(NSString*) objectName
						 objectData:(NSMutableDictionary*) objectData;

/** Creates the given object's hierarchy clean XML inside the given node.

The method will recursively handle all object's children as well. It is sent from
@c createCleanHierarchyDocumentationFile() for each root level node. It should not
be used otherwise.

@param objectHierarchyData The object's @c NSDictionary from the hierarchies data.
@param node The @c NSXMLElement parent within which to create the given object's nodes.
@exception NSException Thrown if creation fails.
*/
- (void) createHierarchyDataForObject:(NSDictionary*) objectHierarchyData
						   withinNode:(NSXMLElement*) node;

/** Fixes inheritance links for the given object.

This fixes base class and protocols links. If the base class or protocol is one of the 
known objects, the link reference is added to the clean document. Additionally, all
protocol @c &lt;base&gt; nodes are renamed to @c &lt;conforms&gt; so that the html creation is
easier later on. This is also where full hierarchy for classes is generated (note that
this relies on the data generated by @c createCleanHierarchyDocumentationFile(), so
this message should be sent afterwards).
 
This message is sent automatically from @c fixCleanObjectDocumentation() and should not
be sent otherwise. It is used to simplify otherwise large and difficult to manage parent
method.

@param objectName The name of the object that should be fixed.
@param objectData The data of the object that should be fixed.
@param objects The dictionary of all objects.
@exception NSException Thrown if fixing fails.
@see fixLocationForObject:objectData:objects:
@see fixReferencesForObject:objectData:objects:
@see fixParaLinksForObject:objectData:objects:
@see fixEmptyParaForObject:objectData:objects:
*/
- (void) fixInheritanceForObject:(NSString*) objectName
					  objectData:(NSMutableDictionary*) objectData
						 objects:(NSDictionary*) objects;

/** Fixes location for classes if necessary.

For some reason doxygen uses a location of one of the class categories for the class
itself if the categories are defined in separate files. This is where we fix such links.
Note that this should optionally be enabled in @c CommandLineParser.
 
This message is sent automatically from @c fixCleanObjectDocumentation() and should not
be sent otherwise. It is used to simplify otherwise large and difficult to manage parent
method.

@param objectName The name of the object that should be fixed.
@param objectData The data of the object that should be fixed.
@param objects The dictionary of all objects.
@exception NSException Thrown if fixing fails.
@see fixInheritanceForObject:objectData:objects:
@see fixReferencesForObject:objectData:objects:
@see fixParaLinksForObject:objectData:objects:
@see fixEmptyParaForObject:objectData:objects:
*/
- (void) fixLocationForObject:(NSString*) objectName
				   objectData:(NSMutableDictionary*) objectData
					  objects:(NSDictionary*) objects;

/** Fixes doxygen references links for the given object.

This updates all doxygen created references specified by @c &lt;ref&gt; tag so that their
reference points to the correct file and/or member. The result is that all @c &lt;ref&gt;
nodes now have correct references prepared for the html generation later on.
 
This message is sent automatically from @c fixCleanObjectDocumentation() and should not
be sent otherwise. It is used to simplify otherwise large and difficult to manage parent
method.

@param objectName The name of the object that should be fixed.
@param objectData The data of the object that should be fixed.
@param objects The dictionary of all objects.
@exception NSException Thrown if fixing fails.
@see fixInheritanceForObject:objectData:objects:
@see fixLocationForObject:objectData:objects:
@see fixParaLinksForObject:objectData:objects:
@see fixEmptyParaForObject:objectData:objects:
*/
- (void) fixReferencesForObject:(NSString*) objectName
					 objectData:(NSMutableDictionary*) objectData
						objects:(NSDictionary*) objects;

/** Fixes all objective-c links ignored by doxygen for the given object.

This will actually check all description paragraphs and scan word by word to see if a
known object is being addressed. If so, it will convert the word to the proper @c &lt;ref&gt;
tag. Therefore all links to classes, protocols and categories are properly handled.
In addition, the code will also convert any word that starts with @c :: or ends with @c ()
to a @c &lt;ref&gt; for the given member. The code will not check if a member with that name
exists or not though, so some care needs to be taken when documenting code...
Further more, doxygen incorrectly handles links to category members and doesn't detect
links to unknown classes. These are also properly detected and converted here.
 
This message is sent automatically from @c fixCleanObjectDocumentation() and should not
be sent otherwise. It is used to simplify otherwise large and difficult to manage parent
method.

@param objectName The name of the object that should be fixed.
@param objectData The data of the object that should be fixed.
@param objects The dictionary of all objects.
@exception NSException Thrown if fixing fails.
@see fixInheritanceForObject:objectData:objects:
@see fixLocationForObject:objectData:objects:
@see fixReferencesForObject:objectData:objects:
@see fixEmptyParaForObject:objectData:objects:
*/
- (void) fixParaLinksForObject:(NSString*) objectName
					objectData:(NSMutableDictionary*) objectData
					   objects:(NSDictionary*) objects;

/** Fixes all empty paragraphs in the documentation for the given object.

Doxygen leaves some paragraphs with only spaces inside. We will delete all such "hanging"
paragraps to get nicer looking documentation. If the user prevented deletion through
@c --no-empty-para command line, this method will not do anything.
 
This message is sent automatically from @c fixCleanObjectDocumentation() and should not
be sent otherwise. It is used to simplify otherwise large and difficult to manage parent
method.

@param objectName The name of the object that should be fixed.
@param objectData The data of the object that should be fixed.
@param objects The dictionary of all objects.
@exception NSException Thrown if fixing fails.
@see fixInheritanceForObject:objectData:objects:
@see fixLocationForObject:objectData:objects:
@see fixReferencesForObject:objectData:objects:
@see fixParaLinksForObject:objectData:objects:
*/
- (void) fixEmptyParaForObject:(NSString*) objectName
					objectData:(NSMutableDictionary*) objectData
					   objects:(NSDictionary*) objects;

//////////////////////////////////////////////////////////////////////////////////////////
/// @name Helper methods
//////////////////////////////////////////////////////////////////////////////////////////

/** Fetches the link data for the given object and member name.

@param objectName The name of the object.
@param memberName The name of the object's member.
@return Returns the @c NSDictionary from the database corresponding to the given object
	member data. Returns @c nil if either object or member is not found.
@see objectLinkNameForObject:andMember:
@see memberLinkNameForObject:andMember:
*/
- (NSDictionary*) linkDataForObject:(NSString*) objectName
						  andMember:(NSString*) memberName;

/** Generates the link name for inter-object link.

@param objectName The name of the object.
@param memberName The name of the object's member.
@return Returns the given link name.
@see linkDataForObject:andMember:
@see memberLinkNameForObject:andMember:
*/
- (NSString*) objectLinkNameForObject:(NSString*) objectName
							andMember:(NSString*) memberName;

/** Generates the link name for a member link.

@param objectName The name of the object.
@param memberName The name of the object's member.
@return Returns the given link name.
@see linkDataForObject:andMember:
@see objectLinkNameForObject:andMember:
*/
- (NSString*) memberLinkNameForObject:(NSString*) objectName
							andMember:(NSString*) memberName;

/** Prepares the link to the given destination object.

The link is prepared for the given @c source object's reference to the given @c destination
object. If the two objects are found in the same subdirectory, the destination file name
is returned. Otherwise the relative link to the destination's file is returned. The
returned link already contains the required html extension.

@param source The object which is reffering to @c destination objecy.
@param destination The object to which the @c object is reffering.
@return Returns the required link, including relative path if necessary.
*/
- (NSString*) objectReferenceFromObject:(NSString*) source 
							   toObject:(NSString*) destination;

/** Generates obsfucated string from the given one.

This is used internally while fixing broken links. The obsfucation is only temporary and
is removed before creating final text. It is not meant to hide contents from human eye
or web robots.

@param string The string to obsfucate.
@return Returns obsfucated string.
*/
- (NSString*) obsfucatedStringFromString:(NSString*) string;

//////////////////////////////////////////////////////////////////////////////////////////
/// @name Properties
//////////////////////////////////////////////////////////////////////////////////////////

/** Sets or returns the @c OutputInfoProvider conformer that provides information about
doxygen files.
 
This value is used to determine the path to the doxygen XML files. It is used to enumerate
the list of all objects and convert the doxygen XML to clean XML which is later as a
foundation for generating usable output by the rest of the output generators.

@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> doxygenInfoProvider;

@end