Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Refactored description blocks documentation extraction.

Instead of forcing the XMLBasedOutputGenerator subclasses dealing with the underlying XML structure (which was the main reason behind the creation of the XMLBasedOutputGenerator class), the subclasses can use extraction methods in the same way as for handling the rest of the output.
  • Loading branch information...
commit 26c268f5f394b76b232dc20c4b158a525eed24fe 1 parent b1fc06f
@tomaz authored
View
2  LoggingProvider.h
@@ -164,6 +164,8 @@ line of text. At least with current browser width. And yea, because I'm not onli
the moment, I cannot use lorem ipsum for that. And I also don't know it from the memory.
There's much more important stuff to remember than that... Except for the cases like this
where the text is actually needed. Well, looks like my imagination is still working...
+
+Here's an example of how to get @b strong or @a emphasized items.
@param param The parameter.
@param value The value.
View
6 Templates/object.xslt
@@ -133,7 +133,11 @@
</xsl:template>
<xsl:template match="bold">
- <bold><xsl:apply-templates/></bold>
+ <strong><xsl:apply-templates/></strong>
+ </xsl:template>
+
+ <xsl:template match="emphasis">
+ <emphasis><xsl:apply-templates/></emphasis>
</xsl:template>
<xsl:template match="para">
View
6 Templates/screen.css
@@ -276,10 +276,14 @@ dl.parameterList dd {
padding-top: 0.3em;
}
-.emphasize {
+.strong {
font-weight: bold;
}
+.emphasize {
+ font-style: italic;
+}
+
/* @end */
/* @group Tooltips */
View
24 XHTMLOutputGenerator.h
@@ -135,8 +135,7 @@ of the given data.
@param item The description item which brief subcsection to append.
@exception NSException Thrown if appending fails.
@see appendDetailedDescriptionToData:fromItem:
-@see appendDescriptionToData:fromParagraphs:
-@see appendDescriptionToData:fromParagraph:
+@see appendDescriptionToData:fromDescription:
*/
- (void) appendBriefDescriptionToData:(NSMutableData*) data
fromItem:(id) item;
@@ -151,27 +150,11 @@ of the given data.
@param item The description item which detailed subcsection to append.
@exception NSException Thrown if appending fails.
@see appendBriefDescriptionToData:fromItem:
-@see appendDescriptionToData:fromParagraphs:
-@see appendDescriptionToData:fromParagraph:
+@see appendDescriptionToData:fromDescription:
*/
- (void) appendDetailedDescriptionToData:(NSMutableData*) data
fromItem:(id) item;
-/** converts the description data from the given paragraphs to proper XHTML format and
-appends it to the given data.
-
-This method is useful for items which contents should be treated as standard descriptions.
-
-@param data The array of paragraphs to append.
-@param paragraphs The array of paragraphs to convert and append. If @c nil nothing will happen.
-@exception NSException Thrown if conversion fails.
-@see appendBriefDescriptionToData:fromItem:
-@see appendDetailedDescriptionToData:fromItem:
-@see appendDescriptionToData:fromParagraph:
-*/
-- (void) appendDescriptionToData:(NSMutableData*) data
- fromParagraphs:(NSArray*) paragraphs;
-
/** Converts the description data from the given paragraph to proper XHTML format and
appends it to the given data.
@@ -184,10 +167,9 @@ data XML structure is exposed to the class.
@exception NSException Thrown if convertion fails.
@see appendBriefDescriptionToData:fromItem:
@see appendDetailedDescriptionToData:fromItem:
-@see appendDescriptionToData:fromParagraphs:
*/
- (void) appendDescriptionToData:(NSMutableData*) data
- fromParagraph:(id) item;
+ fromDescription:(id) item;
//////////////////////////////////////////////////////////////////////////////////////////
/// @name Helper methods
View
149 XHTMLOutputGenerator.m
@@ -397,8 +397,11 @@ - (void) appendObjectMemberSectionToData:(NSMutableData*) data
[self appendString:@" <dd>" toData:data];
id descriptionItem = [self extractObjectParameterDescriptionNode:parameterItem];
- NSArray* paragraphs = [self extractParagraphsFromItem:descriptionItem];
- [self appendDescriptionToData:data fromParagraphs:paragraphs];
+ NSArray* descriptions = [self extractDescriptionsFromItem:descriptionItem];
+ for (id description in descriptions)
+ {
+ [self appendDescriptionToData:data fromDescription:description];
+ }
[self appendLine:@"</dd>" toData:data];
}
[self appendLine:@" </dl>" toData:data];
@@ -413,8 +416,11 @@ - (void) appendObjectMemberReturnToData:(NSMutableData*) data
if (returnItem)
{
[self appendLine:@" <h5>Return value</h5>" toData:data];
- NSArray* paragraphs = [self extractParagraphsFromItem:returnItem];
- [self appendDescriptionToData:data fromParagraphs:paragraphs];
+ NSArray* descriptions = [self extractDescriptionsFromItem:returnItem];
+ for (id description in descriptions)
+ {
+ [self appendDescriptionToData:data fromDescription:description];
+ }
}
}
@@ -425,7 +431,7 @@ - (void) appendObjectMemberDiscussionToData:(NSMutableData*) data
id descriptionItem = [self extractObjectMemberDescriptionItem:item];
if (descriptionItem)
{
- NSArray* paragraphs = [self extractDetailParagraphsFromItem:descriptionItem];
+ NSArray* paragraphs = [self extractDetailDescriptionsFromItem:descriptionItem];
if (paragraphs && [self isDescriptionUsed:paragraphs])
{
[self appendLine:@" <h5>Discussion</h5>" toData:data];
@@ -448,8 +454,11 @@ - (void) appendObjectMemberWarningToData:(NSMutableData*) data
[self appendLine:@" <h5>Warning</h5>" toData:data];
// Append the actual text.
- NSArray* paragraphs = [self extractParagraphsFromItem:warningItem];
- [self appendDescriptionToData:data fromParagraphs:paragraphs];
+ NSArray* descriptions = [self extractDescriptionsFromItem:warningItem];
+ for (id description in descriptions)
+ {
+ [self appendDescriptionToData:data fromDescription:description];
+ }
// Append footer if bordered appearance is desired.
if (cmd.xhtmlUseBorderedWarnings)
@@ -471,8 +480,11 @@ - (void) appendObjectMemberBugToData:(NSMutableData*) data
[self appendLine:@" <h5>Bug</h5>" toData:data];
// Append the actual text.
- NSArray* paragraphs = [self extractParagraphsFromItem:bugItem];
- [self appendDescriptionToData:data fromParagraphs:paragraphs];
+ NSArray* descriptions = [self extractDescriptionsFromItem:bugItem];
+ for (id description in descriptions)
+ {
+ [self appendDescriptionToData:data fromDescription:description];
+ }
// Append footer if bordered appearance is desired.
if (cmd.xhtmlUseBorderedWarnings)
@@ -492,7 +504,7 @@ - (void) appendObjectMemberSeeAlsoToData:(NSMutableData*) data
for (id item in items)
{
[self appendString:@" <li><code>" toData:data];
- [self appendDescriptionToData:data fromParagraph:item];
+ [self appendDescriptionToData:data fromDescription:item];
[self appendLine:@"</code></li>" toData:data];
}
[self appendLine:@" </ul>" toData:data];
@@ -739,63 +751,94 @@ - (void) appendHierarchyGroupItemToData:(NSMutableData*) data
- (void) appendBriefDescriptionToData:(NSMutableData*) data
fromItem:(id) item
{
- NSArray* paragraphs = [self extractBriefParagraphsFromItem:item];
- [self appendDescriptionToData:data fromParagraphs:paragraphs];
+ NSArray* descriptions = [self extractBriefDescriptionsFromItem:item];
+ for (id description in descriptions)
+ {
+ [self appendDescriptionToData:data fromDescription:description];
+ }
}
//----------------------------------------------------------------------------------------
- (void) appendDetailedDescriptionToData:(NSMutableData*) data
fromItem:(id) item
{
- NSArray* paragraphs = [self extractDetailParagraphsFromItem:item];
- [self appendDescriptionToData:data fromParagraphs:paragraphs];
-}
-
-//----------------------------------------------------------------------------------------
-- (void) appendDescriptionToData:(NSMutableData*) data
- fromParagraphs:(NSArray*) paragraphs
-{
- if (paragraphs)
+ NSArray* descriptions = [self extractDetailDescriptionsFromItem:item];
+ for (id description in descriptions)
{
- for (id paragraph in paragraphs)
- {
- [self appendDescriptionToData:data fromParagraph:paragraph];
- }
+ [self appendDescriptionToData:data fromDescription:description];
}
}
-
//----------------------------------------------------------------------------------------
- (void) appendDescriptionToData:(NSMutableData*) data
- fromParagraph:(id) item
+ fromDescription:(id) item
{
- if (item)
+ int type = [self extractDescriptionType:item];
+ switch (type)
{
- NSString* result = [self extractParagraphText:item];
-
- // Handle simple tags replacements.
- result = [result stringByReplacingOccurrencesOfString:@"<para>" withString:@"<p>"];
- result = [result stringByReplacingOccurrencesOfString:@"</para>" withString:@"</p>"];
- result = [result stringByReplacingOccurrencesOfString:@"<ref id" withString:@"<a href"];
- result = [result stringByReplacingOccurrencesOfString:@"</ref>" withString:@"</a>"];
- result = [result stringByReplacingOccurrencesOfString:@"<list>" withString:@"<ul>"];
- result = [result stringByReplacingOccurrencesOfString:@"</list>" withString:@"</ul>"];
- result = [result stringByReplacingOccurrencesOfString:@"<item>" withString:@"<li>"];
- result = [result stringByReplacingOccurrencesOfString:@"</item>" withString:@"</li>"];
-
- // Handle replacements with spans.
- result = [result stringByReplacingOccurrencesOfString:@"<bold>" withString:@"<span class=\"emphasize\">"];
- result = [result stringByReplacingOccurrencesOfString:@"</bold>" withString:@"</span>"];
-
- // Handle the example section.
- NSString* exampleTag = [NSString stringWithFormat:@"<div%@><pre>",
- cmd.xhtmlUseBorderedExamples ?
- @" class=\"example\"" :
- @""];
- result = [result stringByReplacingOccurrencesOfString:@"<example>" withString:exampleTag];
- result = [result stringByReplacingOccurrencesOfString:@"</example>" withString:@"</pre></div>"];
-
- [self appendLine:result toData:data];
+ case kTKDescriptionParagraphStart:
+ [self appendString:@"<p>" toData:data];
+ break;
+ case kTKDescriptionParagraphEnd:
+ [self appendLine:@"</p>" toData:data];
+ break;
+
+ case kTKDescriptionCodeStart:
+ [self appendString:@"<code>" toData:data];
+ break;
+ case kTKDescriptionCodeEnd:
+ [self appendString:@"</code>" toData:data];
+ break;
+
+ case kTKDescriptionListStart:
+ [self appendLine:@"<ul>" toData:data];
+ break;
+ case kTKDescriptionListEnd:
+ [self appendLine:@"</ul>" toData:data];
+ break;
+ case kTKDescriptionListItemStart:
+ [self appendString:@"<li>" toData:data];
+ break;
+ case kTKDescriptionListItemEnd:
+ [self appendLine:@"</li>" toData:data];
+ break;
+
+ case kTKDescriptionStrongStart:
+ [self appendString:@"<span class=\"strong\">" toData:data];
+ break;
+ case kTKDescriptionStrongEnd:
+ [self appendString:@"</span>" toData:data];
+ break;
+
+ case kTKDescriptionEmphasisStart:
+ [self appendString:@"<span class=\"emphasize\">" toData:data];
+ break;
+ case kTKDescriptionEmphasisEnd:
+ [self appendString:@"</span>" toData:data];
+ break;
+
+ case kTKDescriptionExampleStart:
+ if (cmd.xhtmlUseBorderedExamples)
+ [self appendString:@"<div class=\"example\"><pre>" toData:data];
+ else
+ [self appendString:@"<div><pre>" toData:data];
+ break;
+ case kTKDescriptionExampleEnd:
+ [self appendLine:@"</pre></div>" toData:data];
+ break;
+
+ case kTKDescriptionReferenceStart:
+ [self appendString:@"<a href=\"" toData:data];
+ [self appendString:[self extractDescriptionReference:item] toData:data];
+ [self appendString:@"\">" toData:data];
+ break;
+ case kTKDescriptionReferenceEnd:
+ [self appendString:@"</a>" toData:data];
+ break;
+
+ case kTKDescriptionText:
+ [self appendString:[self extractDescriptionText:item] toData:data];
+ break;
}
}
View
173 XMLBasedOutputGenerator+GeneralParsingAPI.h
@@ -27,8 +27,8 @@ useful for generating short descriptions for example.
@param item The description item which brief description to return.
@return Returns the first brief description paragraph text or @c nil if not found.
-@see extractBriefParagraphsFromItem:
-@see extractDetailParagraphsFromItem:
+@see extractBriefDescriptionsFromItem:
+@see extractDetailDescriptionsFromItem:
@see isDescriptionUsed:
*/
- (NSString*) extractBriefDescriptionFromItem:(id) item;
@@ -42,12 +42,14 @@ text of individual paragraphs.
@param item The description item which brief description paragraphs to return.
@return Returns the brief item paragraphs or @c nil if brief is empty.
@see extractBriefDescriptionFromItem:
-@see extractDetailParagraphsFromItem:
-@see extractParagraphsFromItem:
-@see extractParagraphText:
+@see extractDetailDescriptionsFromItem:
+@see extractDescriptionsFromItem:
+@see extractDescriptionType:
+@see extractDescriptionReference:
+@see extractDescriptionText:
@see isDescriptionUsed:
*/
-- (NSArray*) extractBriefParagraphsFromItem:(id) item;
+- (NSArray*) extractBriefDescriptionsFromItem:(id) item;
/** Extracts the detailed description paragraphs from the given description item.
@@ -58,40 +60,132 @@ text of individual paragraphs.
@param item The description item which detailed description paragraphs to return.
@return Returns the detailed node paragraphs or @c nil if details are empty.
@see extractBriefDescriptionFromItem:
-@see extractBriefParagraphsFromItem:
-@see extractParagraphsFromItem:
-@see extractParagraphText:
+@see extractBriefDescriptionsFromItem:
+@see extractDescriptionsFromItem:
+@see extractDescriptionType:
+@see extractDescriptionReference:
+@see extractDescriptionText:
@see isDescriptionUsed:
*/
-- (NSArray*) extractDetailParagraphsFromItem:(id) item;
+- (NSArray*) extractDetailDescriptionsFromItem:(id) item;
/** Extracts the paragraphs from the given item.
This method can be used for any item which contains the list of paragraphs. Internally
-it is also used to extract the paragraphs in the @c extractBriefParagraphsFromItem:()
-and @c extractDetailParagraphsFromItem:().
+it is also used to extract the paragraphs in the @c extractBriefDescriptionsFromItem:()
+and @c extractDetailDescriptionsFromItem:().
@param item The item which paragraphs contents to extract.
-@return Returns the array paragraphs or @c nil if no paragraph is found.
+@return Returns the array of paragraphs or @c nil if no paragraph is found.
@see extractBriefDescriptionFromItem:
-@see extractBriefParagraphsFromItem:
-@see extractDetailParagraphsFromItem:
-@see extractParagraphText:
+@see extractBriefDescriptionsFromItem:
+@see extractDetailDescriptionsFromItem:
+@see extractDescriptionType:
+@see extractDescriptionReference:
+@see extractDescriptionText:
@see isDescriptionUsed:
*/
-- (NSArray*) extractParagraphsFromItem:(id) item;
+- (NSArray*) extractDescriptionsFromItem:(id) item;
-/** Extracts the given paragraph item text.
+/** Extracts the type of the given description item.
-@param item The paragraph item to extract.
-@return Returns the paragraph text or @c nil if not found.
-@see extractBriefDescriptionFromItem:
-@see extractBriefParagraphsFromItem:
-@see extractDetailParagraphsFromItem:
-@see extractParagraphsFromItem:
-@see isDescriptionUsed:
+This method can be used to get the information about the type of the given description
+item extracted through one of the following methods: @c extractBriefDescriptionsFromItem:(),
+@c extractDetailDescriptionsFromItem:(), @c extractDescriptionsFromItem:().
+
+Possible return values are:
+- @c kTKDescriptionParagraphStart: The description represents a paragraph block start
+ which ends with an @c kTKDescriptionParagraphEnd. In between any number of the other
+ items type may be extracted.
+- @c kTKDescriptionParagraphEnd: The description represents a paragraph end. Each
+ paragraph block opened with @c kTKDescriptionParagraphStart ends with this item.
+- @c kTKDescriptionCodeStart: The description represents a code block start
+ which ends with an @c kTKDescriptionCodeEnd. In between any number of the other
+ items type may be extracted.
+- @c kTKDescriptionCodeEnd: The description represents a code end. Each code block opened
+ with @c kTKDescriptionCodeStart ends with this item.
+- @c kTKDescriptionListStart: The description represents a list block start which ends
+ with an @c kTKDescriptionCodeEnd. In between any number of list item blocks may be
+ reported.
+- @c kTKDescriptionListEnd: The description represents a list end. Each list block opened
+ with @c kTKDescriptionListStart ends with this item.
+- @c kTKDescriptionListItemStart: The description represents a list item block start
+ which ends with an @c kTKDescriptionListItemEnd. In between any number of the other
+ items type may be extracted.
+- @c kTKDescriptionListItemEnd: The description represents a list item end. Each list item
+ block opened with @c kTKDescriptionListItemStart ends with this item.
+- @c kTKDescriptionStrongStart: The description represents a strong type block start which
+ ends with an @c kTKDescriptionStrongEnd. In between any number of the other items type
+ may be extracted.
+- @c kTKDescriptionStrongEnd: The description represents a strong tyoe item end. Each
+ strong type block opened with @c kTKDescriptionStrongStart ends with this item.
+- @c kTKDescriptionEmphasisStart: The description represents an emphasis type block start
+ which ends with an @c kTKDescriptionEmphasisEnd. In between any number of the other
+ items type may be extracted.
+- @c kTKDescriptionEmphasisEnd: The description represents an emphasis type block end. Each
+ emphasis type block opened with @c kTKDescriptionEmphasisStart ends with this item.
+- @c kTKDescriptionExampleStart The description represents an example block start which
+ ends with an @c kTKDescriptionExampleEnd. In between any number of other items may
+ be reported (although example blocks ussually only contain @c kTKDescriptionText
+ sub items).
+- @c kTKDescriptionExampleEnd: The description represents an example block end. Each
+ example block opened with @c kTKDescriptionExampleStart ends with this item.
+- @c kTKDescriptionReferenceStart: The description represents a reference block start
+ which ends with an @c kTKDescriptionReferenceEnd. The opening description should
+ be querried for the actual link with @c extractDescriptionReference:(). The
+ description name will be reported immediately after opening item with the
+ @c kTKDescriptionText item, followed by the @c kTKDescriptionReferenceEnd.
+- @c kTKDescriptionReferenceEnd: The description represents a reference item end. Each
+ reference block opened with @c kTKDescriptionReferenceStart ends with this item.
+- @c kTKDescriptionText: The description represents a normal text. @c extractDescriptionText:()
+ message may be sent to get the text value.
+
+@param item The item which type to return.
+@return Returns the type of the given item.
+@exception Thrown if the given item is not recognised.
+@see extractBriefDescriptionsFromItem:
+@see extractDetailDescriptionsFromItem:
+@see extractDescriptionsFromItem:
+@see extractDescriptionReference:
+@see extractDescriptionText:
+*/
+- (int) extractDescriptionType:(id) item;
+
+/** Extracts the description reference from the given description item.
+
+This method can be used to get the information about the reference link from description
+item extracted through one of the following methods: @c extractBriefDescriptionsFromItem:(),
+@c extractDetailDescriptionsFromItem:(), @c extractDescriptionsFromItem:().
+
+@param description The @c kTKDescriptionReferenceStart description item to extract from.
+@return Returns the reference value of the given item.
+@warning @b Important: This only returns valid values for description types of
+ @c kTKDescriptionReferenceStart. It returns @c nil for all other description types.
+@see extractBriefDescriptionsFromItem:
+@see extractDetailDescriptionsFromItem:
+@see extractDescriptionsFromItem:
+@see extractDescriptionType:
+@see extractDescriptionText:
*/
-- (NSString*) extractParagraphText:(id) item;
+- (NSString*) extractDescriptionReference:(id) description;
+
+/** Extracts the description text from the given description item.
+
+This method can be used to get the information about the actual text from description
+item extracted through one of the following methods: @c extractBriefDescriptionsFromItem:(),
+@c extractDetailDescriptionsFromItem:(), @c extractDescriptionsFromItem:().
+
+@param item The @c kTKDescriptionText description item to extract from.
+@return Returns the text value of the given item.
+@warning @b Important: This only returns valid values for description types of
+ @c kTKDescriptionText. It returns invalid values for all other description types.
+@see extractBriefDescriptionsFromItem:
+@see extractDetailDescriptionsFromItem:
+@see extractDescriptionsFromItem:
+@see extractDescriptionType:
+@see extractDescriptionText:
+*/
+- (NSString*) extractDescriptionText:(id) item;
/** Determines if at least one of the given brief or detailed paragraphs is used or not.
@@ -102,9 +196,9 @@ source in previous steps, but some may still be present...
@param nodes The array returned from description parsing methods.
@return Returns @c YES if at least one paragraph contains some text.
@see extractBriefDescriptionFromItem:
-@see extractBriefParagraphsFromItem:
-@see extractDetailParagraphsFromItem:
-@see extractParagraphsFromItem:
+@see extractBriefDescriptionsFromItem:
+@see extractDetailDescriptionsFromItem:
+@see extractDescriptionsFromItem:
*/
- (BOOL) isDescriptionUsed:(NSArray*) nodes;
@@ -119,12 +213,29 @@ Note that this method always returns the first subitem if more than one exists.
@param item The item to extract from.
@param name The name of the subitem to extract.
@return Returns the given subitem or @c nil if doesn't exist.
-@warning This method is here because other methods from the category need it, the method
- should not be used by the subclasses and should be regarded as internal!
+@warning @b Important: This method is here because other methods from the category need
+ it. It should not be used by the subclasses and should be regarded as internal!
+@see extractSubitemsFromItem:appendToArray:closeContainers:
*/
- (id) extractSubitemFromItem:(id) item
withName:(NSString*) name;
+/** Extracts all sub items from the given item.
+
+Note that this returns the whole hierarchy of sub-items in proper order. Optionally,
+this can also close all container sub-items.
+
+@param item The item which subitems to extract.
+@param array The array to which to append the items.
+@param close If @c YES, all container sub-items are "closed", otherwise not.
+@warning @b Important: This method is here because other methods from the category need
+ it. It should not be used by the subclasses and should be regarded as internal!
+@see extractSubitemFromItem:withName:
+*/
+- (void) extractSubitemsFromItem:(id) item
+ appendToArray:(NSMutableArray*) array
+ closeContainers:(BOOL) close;
+
//////////////////////////////////////////////////////////////////////////////////////////
/// @name Helper generation methods
//////////////////////////////////////////////////////////////////////////////////////////
View
101 XMLBasedOutputGenerator+GeneralParsingAPI.m
@@ -7,6 +7,7 @@
//
#import "XMLBasedOutputGenerator+GeneralParsingAPI.h"
+#import "Systemator.h"
@implementation XMLBasedOutputGenerator (GeneralParsingAPI)
@@ -17,39 +18,97 @@ @implementation XMLBasedOutputGenerator (GeneralParsingAPI)
//----------------------------------------------------------------------------------------
- (NSString*) extractBriefDescriptionFromItem:(id) item
{
- NSArray* subnodes = [self extractBriefParagraphsFromItem:item];
+ NSArray* subnodes = [self extractBriefDescriptionsFromItem:item];
if (subnodes) return [[subnodes objectAtIndex:0] stringValue];
return nil;
}
//----------------------------------------------------------------------------------------
-- (NSArray*) extractBriefParagraphsFromItem:(id) item
+- (NSArray*) extractBriefDescriptionsFromItem:(id) item
{
NSXMLElement* briefNode = [self extractSubitemFromItem:item withName:@"brief"];
- if (briefNode) return [self extractParagraphsFromItem:briefNode];
+ if (briefNode) return [self extractDescriptionsFromItem:briefNode];
return nil;
}
//----------------------------------------------------------------------------------------
-- (NSArray*) extractDetailParagraphsFromItem:(id) item
+- (NSArray*) extractDetailDescriptionsFromItem:(id) item
{
NSXMLElement* detailsNode = [self extractSubitemFromItem:item withName:@"details"];
- if (detailsNode) return [self extractParagraphsFromItem:detailsNode];
+ if (detailsNode) return [self extractDescriptionsFromItem:detailsNode];
return nil;
}
//----------------------------------------------------------------------------------------
-- (NSArray*) extractParagraphsFromItem:(id) item
+- (NSArray*) extractDescriptionsFromItem:(id) item
{
- NSArray* result = [item nodesForXPath:@"*" error:nil];
+ // Extract all children (recursively!) from the given description item.
+ NSMutableArray* result = [NSMutableArray array];
+ [self extractSubitemsFromItem:item appendToArray:result closeContainers:YES];
+
+ // If there is at least one child, process it - we need to "close"
if ([result count] > 0) return result;
return nil;
}
//----------------------------------------------------------------------------------------
-- (NSString*) extractParagraphText:(id) item
+- (int) extractDescriptionType:(id) item
{
- return [item XMLString];
+ // If the given item is an element, get the type based on element name. Note that
+ // we kind of hack close elements handling to make the code simpler and avoid
+ // repetition: since these are elements with the same name as their opening
+ // counterparts except they have close=YES attribute, we use the same detection
+ // code, but add 1 to the result. Therefore the code depends on the fact that all
+ // close types should have the value of open type + 1!
+ if ([item kind] == NSXMLElementKind)
+ {
+ // Is this close node? If we find close attribute (we don't even check the
+ // value), we should add 1 to the result, otherwise 0.
+ int offset = [item attributeForName:@"close"] ? 1 : 0;
+
+ // Now handle the name. Note that we return the type + the calculated offset.
+ if ([[item name] isEqualToString:@"para"])
+ return kTKDescriptionParagraphStart + offset;
+ if ([[item name] isEqualToString:@"code"])
+ return kTKDescriptionCodeStart + offset;
+ if ([[item name] isEqualToString:@"list"])
+ return kTKDescriptionListStart + offset;
+ if ([[item name] isEqualToString:@"item"])
+ return kTKDescriptionListItemStart + offset;
+ if ([[item name] isEqualToString:@"strong"])
+ return kTKDescriptionStrongStart + offset;
+ if ([[item name] isEqualToString:@"emphasis"])
+ return kTKDescriptionEmphasisStart + offset;
+ if ([[item name] isEqualToString:@"example"])
+ return kTKDescriptionExampleStart + offset;
+ if ([[item name] isEqualToString:@"ref"])
+ return kTKDescriptionReferenceStart + offset;
+ }
+
+ // If the type is text, return text.
+ else if ([item kind] == NSXMLTextKind)
+ {
+ return kTKDescriptionText;
+ }
+
+ // If we couldn't determine the type, raise an exception.
+ NSString* message = [NSString stringWithFormat:@"Description item '%@' is unknown!", item];
+ [Systemator throwExceptionWithName:kTKConverterException withDescription:message];
+ return -1;
+}
+
+//----------------------------------------------------------------------------------------
+- (NSString*) extractDescriptionReference:(id) description
+{
+ NSXMLNode* idAttribute = [description attributeForName:@"id"];
+ if (idAttribute) return [idAttribute stringValue];
+ return nil;
+}
+
+//----------------------------------------------------------------------------------------
+- (NSString*) extractDescriptionText:(id) item
+{
+ return [item stringValue];
}
//----------------------------------------------------------------------------------------
@@ -79,6 +138,30 @@ - (id) extractSubitemFromItem:(id) item
return nil;
}
+//----------------------------------------------------------------------------------------
+- (void) extractSubitemsFromItem:(id) item
+ appendToArray:(NSMutableArray*) array
+ closeContainers:(BOOL) close
+{
+ // Handle all children and their children. This ends in recursic descent through the
+ // XML hierarchy. Note that we close containers with an element of the same name as
+ // the opening node, but with an attribute close="YES".
+ for (NSXMLNode* node in [item children])
+ {
+ [array addObject:node];
+ if ([node childCount] > 0)
+ {
+ [self extractSubitemsFromItem:node appendToArray:array closeContainers:close];
+ if (close)
+ {
+ NSXMLElement* closeNode = [NSXMLNode elementWithName:[node name]];
+ [closeNode addAttribute:[NSXMLNode attributeWithName:@"close" stringValue:@"YES"]];
+ [array addObject:closeNode];
+ }
+ }
+ }
+}
+
//////////////////////////////////////////////////////////////////////////////////////////
#pragma mark Helper methods
//////////////////////////////////////////////////////////////////////////////////////////
View
4 XMLBasedOutputGenerator+ObjectParsingAPI.h
@@ -152,7 +152,7 @@ individual components. Then use @c extractObjectMemberPrototypeItemType:() and
/** Extracts the member description item from the given member item.
The returned item can be used by @c extractBriefDescriptionFromItem:(),
-@c extractBriefParagraphsFromItem:() and @c extractDetailParagraphsFromItem:() to get
+@c extractBriefDescriptionsFromItem:() and @c extractDetailDescriptionsFromItem:() to get
individual description components.
@param item The member item which description item to return.
@@ -352,7 +352,7 @@ This can be used over the items of the array returned from
/** Extracts the parameter description item from the given parameter item.
The returned item can be used by @c extractBriefDescriptionFromItem:(),
-@c extractBriefParagraphsFromItem:() and @c extractDetailParagraphsFromItem:() to get
+@c extractBriefDescriptionsFromItem:() and @c extractDetailDescriptionsFromItem:() to get
individual description components.
@param item The parameter item which description item to return.
View
25 XMLBasedOutputGenerator.h
@@ -41,8 +41,31 @@ enum TKGeneratorObjectMemberSectionTypes
kTKObjectMemberSectionExceptions,
};
+/** Defines different description item types. Description item types are used when
+appending brief or detailed description. */
+enum TKGeneratorDescriptionItemTypes
+{
+ kTKDescriptionParagraphStart,
+ kTKDescriptionParagraphEnd,
+ kTKDescriptionCodeStart,
+ kTKDescriptionCodeEnd,
+ kTKDescriptionListStart,
+ kTKDescriptionListEnd,
+ kTKDescriptionListItemStart,
+ kTKDescriptionListItemEnd,
+ kTKDescriptionStrongStart,
+ kTKDescriptionStrongEnd,
+ kTKDescriptionEmphasisStart,
+ kTKDescriptionEmphasisEnd,
+ kTKDescriptionExampleStart,
+ kTKDescriptionExampleEnd,
+ kTKDescriptionReferenceStart,
+ kTKDescriptionReferenceEnd,
+ kTKDescriptionText,
+};
+
/** Defines different index group types. These are used mainly to simplify the code and
- avoid repetition since all of the groups use the same layout. */
+avoid repetition since all of the groups use the same layout. */
enum TKGeneratorIndexGroupTypes
{
kTKIndexGroupClasses,
Please sign in to comment.
Something went wrong with that request. Please try again.