XMLOutputGenerator class reference

OutputGenerator : NSObject
XMLOutputGenerator.h

Overview

Defines a concrete OutputGenerator which generates clean XML documentation.

The generator depends on 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.

Tasks

Properties

Clean XML handling

Clean XML "makeup" handling

Helper methods

Instance methods

createCleanObjectDocumentationMarkup

Creates clean object XML markups.

- (void)createCleanObjectDocumentationMarkup
Exceptions
NSException

Thrown if convertion fails.

Discussion

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 NSXMLParser to the 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 -[OutputGenerator generateSpecificOutput] in the proper order. It is not designed to be sent manually from the clients.

See also
Declared in
XMLOutputGenerator.h

mergeCleanCategoriesToKnownObjects

Merges known object categories to their parent objects is desired.

- (void)mergeCleanCategoriesToKnownObjects
Exceptions
NSException

Thrown if convertion fails.

Discussion

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.

See also
Declared in
XMLOutputGenerator.h

updateCleanObjectsDatabase

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

- (void)updateCleanObjectsDatabase
Exceptions
NSException

Thrown if conversion fails.

Discussion

This message needs to be sent after - mergeCleanCategoriesToKnownObjects and before - fixCleanObjectDocumentation. It handles the following:

See also
Declared in
XMLOutputGenerator.h

createCleanIndexDocumentationFile

Creates clean index XML file.

- (void)createCleanIndexDocumentationFile
Exceptions
NSException

Thrown if index file creation fails.

Discussion

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

This message is automatically sent from -[OutputGenerator generateSpecificOutput] in the proper order. It is not designed to be sent manually from the clients.

See also
Declared in
XMLOutputGenerator.h

createCleanHierarchyDocumentationFile

Creates clean hieararchy XML file.

- (void)createCleanHierarchyDocumentationFile
Exceptions
NSException

Thrown if index file creation fails.

Discussion

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

This message is automatically sent from -[OutputGenerator generateSpecificOutput] in the proper order. It is not designed to be sent manually from the clients.

See also
Declared in
XMLOutputGenerator.h

fixCleanObjectDocumentation

Fixes the clean object XML documentation.

- (void)fixCleanObjectDocumentation
Exceptions
NSException

Thrown if fixing XML fails.

Discussion

This method will scan through all XML files generated in - 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:

This message is automatically sent from -[OutputGenerator generateSpecificOutput] in the proper order. It is not designed to be sent manually from the clients.

See also
Declared in
XMLOutputGenerator.h

saveCleanObjectDocumentationFiles

Saved clean object XML markups to proper files.

- (void)saveCleanObjectDocumentationFiles
Exceptions
NSException

Thrown if saving fails.

Discussion

This method will save all clean XML markups in the database to proper files.

This message is automatically sent from -[OutputGenerator generateSpecificOutput] in the proper order. It is not designed to be sent manually from the clients.

See also
Declared in
XMLOutputGenerator.h

createMembersDataForObject:objectData:

Creates the members entry within the given object data.

- (void)createMembersDataForObject:(NSString *) objectName objectData:(NSMutableDictionary *) objectData
Parameters
objectName

The name of the object for which we should create members.

objectData

The data of the object into which to create the members.

Exceptions
NSException

Thrown if creation fails.

Discussion

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 updateCleanObjectsDatabase for each documented object and should not be sent otherwise. It is used to simplify otherwise large and difficult to manage parent method.

See also
Declared in
XMLOutputGenerator.h

createHierarchyDataForObject:withinNode:

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

- (void)createHierarchyDataForObject:(NSDictionary *) objectHierarchyData withinNode:(NSXMLElement *) node
Parameters
objectHierarchyData

The object's NSDictionary from the hierarchies data.

node

The NSXMLElement parent within which to create the given object's nodes.

Exceptions
NSException

Thrown if creation fails.

Discussion

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

Declared in
XMLOutputGenerator.h

fixInheritanceForObject:objectData:objects:

Fixes inheritance links for the given object.

- (void)fixInheritanceForObject:(NSString *) objectName objectData:(NSMutableDictionary *) objectData objects:(NSDictionary *) objects
Parameters
objectName

The name of the object that should be fixed.

objectData

The data of the object that should be fixed.

objects

The dictionary of all objects.

Exceptions
NSException

Thrown if fixing fails.

Discussion

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 nodes are renamed to 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 - createCleanHierarchyDocumentationFile, so this message should be sent afterwards).

This message is sent automatically from - fixCleanObjectDocumentation and should not be sent otherwise. It is used to simplify otherwise large and difficult to manage parent method.

See also
Declared in
XMLOutputGenerator.h

fixLocationForObject:objectData:objects:

Fixes location for classes if necessary.

- (void)fixLocationForObject:(NSString *) objectName objectData:(NSMutableDictionary *) objectData objects:(NSDictionary *) objects
Parameters
objectName

The name of the object that should be fixed.

objectData

The data of the object that should be fixed.

objects

The dictionary of all objects.

Exceptions
NSException

Thrown if fixing fails.

Discussion

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 CommandLineParser.

This message is sent automatically from - fixCleanObjectDocumentation and should not be sent otherwise. It is used to simplify otherwise large and difficult to manage parent method.

See also
Declared in
XMLOutputGenerator.h

fixReferencesForObject:objectData:objects:

Fixes doxygen references links for the given object.

- (void)fixReferencesForObject:(NSString *) objectName objectData:(NSMutableDictionary *) objectData objects:(NSDictionary *) objects
Parameters
objectName

The name of the object that should be fixed.

objectData

The data of the object that should be fixed.

objects

The dictionary of all objects.

Exceptions
NSException

Thrown if fixing fails.

Discussion

This updates all doxygen created references specified by tag so that their reference points to the correct file and/or member. The result is that all nodes now have correct references prepared for the html generation later on.

This message is sent automatically from - fixCleanObjectDocumentation and should not be sent otherwise. It is used to simplify otherwise large and difficult to manage parent method.

See also
Declared in
XMLOutputGenerator.h

fixParaLinksForObject:objectData:objects:

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

- (void)fixParaLinksForObject:(NSString *) objectName objectData:(NSMutableDictionary *) objectData objects:(NSDictionary *) objects
Parameters
objectName

The name of the object that should be fixed.

objectData

The data of the object that should be fixed.

objects

The dictionary of all objects.

Exceptions
NSException

Thrown if fixing fails.

Discussion

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 tag. Therefore all links to classes, protocols and categories are properly handled. In addition, the code will also convert any word that starts with :: or ends with () to a 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 - fixCleanObjectDocumentation and should not be sent otherwise. It is used to simplify otherwise large and difficult to manage parent method.

See also
Declared in
XMLOutputGenerator.h

fixEmptyParaForObject:objectData:objects:

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

- (void)fixEmptyParaForObject:(NSString *) objectName objectData:(NSMutableDictionary *) objectData objects:(NSDictionary *) objects
Parameters
objectName

The name of the object that should be fixed.

objectData

The data of the object that should be fixed.

objects

The dictionary of all objects.

Exceptions
NSException

Thrown if fixing fails.

Discussion

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 --no-empty-para command line, this method will not do anything.

This message is sent automatically from - fixCleanObjectDocumentation and should not be sent otherwise. It is used to simplify otherwise large and difficult to manage parent method.

See also
Declared in
XMLOutputGenerator.h

linkDataForObject:andMember:

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

- (NSDictionary *)linkDataForObject:(NSString *) objectName andMember:(NSString *) memberName
Parameters
objectName

The name of the object.

memberName

The name of the object's member.

Return value

Returns the NSDictionary from the database corresponding to the given object member data. Returns nil if either object or member is not found.

See also
Declared in
XMLOutputGenerator.h

objectLinkNameForObject:andMember:

Generates the link name for inter-object link.

- (NSString *)objectLinkNameForObject:(NSString *) objectName andMember:(NSString *) memberName
Parameters
objectName

The name of the object.

memberName

The name of the object's member.

Return value

Returns the given link name.

See also
Declared in
XMLOutputGenerator.h

memberLinkNameForObject:andMember:

Generates the link name for a member link.

- (NSString *)memberLinkNameForObject:(NSString *) objectName andMember:(NSString *) memberName
Parameters
objectName

The name of the object.

memberName

The name of the object's member.

Return value

Returns the given link name.

See also
Declared in
XMLOutputGenerator.h

objectReferenceFromObject:toObject:

Prepares the link to the given destination object.

- (NSString *)objectReferenceFromObject:(NSString *) source toObject:(NSString *) destination
Parameters
source

The object which is reffering to destination objecy.

destination

The object to which the object is reffering.

Return value

Returns the required link, including relative path if necessary.

Discussion

The link is prepared for the given source object's reference to the given 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.

Declared in
XMLOutputGenerator.h

obsfucatedStringFromString:

Generates obsfucated string from the given one.

- (NSString *)obsfucatedStringFromString:(NSString *) string
Parameters
string

The string to obsfucate.

Return value

Returns obsfucated string.

Discussion

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.

Declared in
XMLOutputGenerator.h

Properties

doxygenInfoProvider

Sets or returns the OutputInfoProvider conformer that provides information about doxygen files.

@property id doxygenInfoProvider
Discussion

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.

Clients need to set this before starting output generation. If they fail to provide a valid object, generation immediately fails with an exception.

Declared in
XMLOutputGenerator.h

© 2008-2009 Tomaz Kragelj. All rights reserved. (Last updated: 2009-08-24)
Back to index / hierarchy.