Permalink
Browse files

Implemented XHTML bordered examples, warnings and bugs generation.

This can optionally be switched on or off either through the command line or global parameters. Note that while the command parameters only support a single switch that changes the status of all three items, global parameters allow enabling or disabling each individual item type.

Note that at this point, example sections are not parsed properly yet.
  • Loading branch information...
1 parent 23db9d3 commit 0a190cff0736d2aee99f9799c273c10b2d4368db @tomaz committed Jun 3, 2009
Showing with 218 additions and 35 deletions.
  1. +16 −0 CommandLineParser.h
  2. +33 −0 CommandLineParser.m
  3. +20 −0 GeneratorBase+GeneralParsingAPI.h
  4. +11 −11 GeneratorBase+GeneralParsingAPI.m
  5. +25 −0 LoggingProvider.h
  6. +13 −0 Readme.markdown
  7. +24 −0 Templates/screen.css
  8. +23 −1 XHTMLGenerator.h
  9. +53 −23 XHTMLGenerator.m
View
@@ -136,6 +136,22 @@ Note That @c createCleanXHTML() is a prerequisite for documentation set. */
@property(readonly) BOOL createDocSet;
//////////////////////////////////////////////////////////////////////////////////////////
+/// @name <#description#>Properties - XHTML output creation
+//////////////////////////////////////////////////////////////////////////////////////////
+
+/** If @c YES, use bordered XHTML example sections which results in more Apple like
+documentation. */
+@property(readonly) BOOL xhtmlUseBorderedExamples;
+
+/** If @c YES, use bordered XHTML warning sections which results in more Apple like
+documentation. */
+@property(readonly) BOOL xhtmlUseBorderedWarnings;
+
+/** If @c YES, use bordered XHTML bug sections which results in more Apple like
+documentation. */
+@property(readonly) BOOL xhtmlUseBorderedBugs;
+
+//////////////////////////////////////////////////////////////////////////////////////////
/// @name Properties - documentation set creation
//////////////////////////////////////////////////////////////////////////////////////////
View
@@ -32,6 +32,10 @@
#define kTKCmdCreateCleanXHTMLKey @"CreateXHTML" // NSNumber / BOOL
#define kTKCmdCreateDocSetKey @"CreateDocSet" // NSNumber / BOOL
+#define kTKCmdXHTMLBorderedExamplesKey @"XHTMLUseBorderedExamples" // NSNumber / BOOL
+#define kTKCmdXHTMLBorderedWarningsKey @"XHTMLUseBorderedWarnings" // NSNumber / BOOL
+#define kTKCmdXHTMLBorderedBugsKey @"XHTMLUseBorderedBugs" // NSNumber / BOOL
+
#define kTKCmdDocSetBundleIDKey @"DocSetBundleID" // NSString
#define kTKCmdDocSetBundleFeedKey @"DocSetBundleFeed" // NSString
#define kTKCmdDocSetSourcePlistKey @"DocSetSourcePlist" // NSString
@@ -339,6 +343,10 @@ - (void) parseCommandLineArguments:(const char**) argv
[self parseBooleanWithShortcut:nil andName:@"--xhtml" withValue:YES forKey:kTKCmdCreateCleanXHTMLKey];
[self parseBooleanWithShortcut:nil andName:@"--docset" withValue:YES forKey:kTKCmdCreateDocSetKey];
+ [self parseBooleanWithShortcut:nil andName:@"--xhtml-bordered-issues" withValue:YES forKey:kTKCmdXHTMLBorderedExamplesKey];
+ [self parseBooleanWithShortcut:nil andName:@"--xhtml-bordered-issues" withValue:YES forKey:kTKCmdXHTMLBorderedWarningsKey];
+ [self parseBooleanWithShortcut:nil andName:@"--xhtml-bordered-issues" withValue:YES forKey:kTKCmdXHTMLBorderedBugsKey];
+
[self parseStringWithShortcut:nil andName:@"--docid" forKey:kTKCmdDocSetBundleIDKey];
[self parseStringWithShortcut:nil andName:@"--docfeed" forKey:kTKCmdDocSetBundleFeedKey];
[self parseStringWithShortcut:nil andName:@"--docplist" forKey:kTKCmdDocSetSourcePlistKey];
@@ -462,6 +470,9 @@ - (void) printUsage
printf(" --xhtml\n");
printf(" --docset\n");
printf("\n");
+ printf("OPTIONS - XHTML output creation\n");
+ printf(" --xhtml-bordered-issues\n");
+ printf("\n");
printf("OPTIONS - documentation set\n");
printf(" --docid <id>\n");
printf(" --docfeed <name>\n");
@@ -854,6 +865,28 @@ - (BOOL) createDocSet
}
//////////////////////////////////////////////////////////////////////////////////////////
+#pragma mark Properties - XHTML creation
+//////////////////////////////////////////////////////////////////////////////////////////
+
+//----------------------------------------------------------------------------------------
+- (BOOL) xhtmlUseBorderedExamples
+{
+ return [[parameters objectForKey:kTKCmdXHTMLBorderedExamplesKey] boolValue];
+}
+
+//----------------------------------------------------------------------------------------
+- (BOOL) xhtmlUseBorderedWarnings
+{
+ return [[parameters objectForKey:kTKCmdXHTMLBorderedWarningsKey] boolValue];
+}
+
+//----------------------------------------------------------------------------------------
+- (BOOL) xhtmlUseBorderedBugs
+{
+ return [[parameters objectForKey:kTKCmdXHTMLBorderedBugsKey] boolValue];
+}
+
+//////////////////////////////////////////////////////////////////////////////////////////
#pragma mark Properties - documentation set creation
//////////////////////////////////////////////////////////////////////////////////////////
@@ -42,6 +42,7 @@ text of individual paragraphs.
@return Returns the brief item paragraphs or @c nil if brief is empty.
@see extractBriefDescriptionFromItem:
@see extractDetailParagraphsFromItem:
+@see extractParagraphsFromItem:
@see extractParagraphText:
@see isDescriptionUsed:
*/
@@ -57,18 +58,36 @@ text of individual paragraphs.
@return Returns the detailed node paragraphs or @c nil if details are empty.
@see extractBriefDescriptionFromItem:
@see extractBriefParagraphsFromItem:
+@see extractParagraphsFromItem:
@see extractParagraphText:
@see isDescriptionUsed:
*/
- (NSArray*) extractDetailParagraphsFromItem:(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:().
+
+@param item The item which paragraphs contents to extract.
+@return Returns the array paragraphs or @c nil if no paragraph is found.
+@see extractBriefDescriptionFromItem:
+@see extractBriefParagraphsFromItem:
+@see extractDetailParagraphsFromItem:
+@see extractParagraphText:
+@see isDescriptionUsed:
+*/
+- (NSArray*) extractParagraphsFromItem:(id) item;
+
/** Extracts the given paragraph item text.
@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:
*/
- (NSString*) extractParagraphText:(id) item;
@@ -84,6 +103,7 @@ source in previous steps, but some may still be present...
@see extractBriefDescriptionFromItem:
@see extractBriefParagraphsFromItem:
@see extractDetailParagraphsFromItem:
+@see extractParagraphsFromItem:
*/
- (BOOL) isDescriptionUsed:(NSArray*) nodes;
@@ -27,23 +27,23 @@ - (NSString*) extractBriefDescriptionFromItem:(id) item
- (NSArray*) extractBriefParagraphsFromItem:(id) item
{
NSXMLElement* briefNode = [self extractSubitemFromItem:item withName:@"brief"];
- if (briefNode)
- {
- NSArray* result = [briefNode nodesForXPath:@"*" error:nil];
- if ([result count] > 0) return result;
- }
+ if (briefNode) [self extractParagraphsFromItem:briefNode];
return nil;
}
//----------------------------------------------------------------------------------------
- (NSArray*) extractDetailParagraphsFromItem:(id) item
{
- NSXMLElement* briefNode = [self extractSubitemFromItem:item withName:@"details"];
- if (briefNode)
- {
- NSArray* result = [briefNode nodesForXPath:@"*" error:nil];
- if ([result count] > 0) return result;
- }
+ NSXMLElement* detailsNode = [self extractSubitemFromItem:item withName:@"details"];
+ if (detailsNode) return [self extractParagraphsFromItem:detailsNode];
+ return nil;
+}
+
+//----------------------------------------------------------------------------------------
+- (NSArray*) extractParagraphsFromItem:(id) item
+{
+ NSArray* result = [item nodesForXPath:@"*" error:nil];
+ if ([result count] > 0) return result;
return nil;
}
View
@@ -136,6 +136,31 @@ derived classes documentation handling...
*/
@interface SuperLogger : Logger <Blabla1, Blabla2, Blabla3>
+/** This method does nothing.
+
+Except it uses warning and bug keywords so that we can test them easily in the generated
+output. It also shows how to use code segments. Well because of all these features, bells
+and whistles, the generated output looks kind of... well... see for yourself
+
+@verbatim
+[SuperLogger thisMethodUsesWarningAndBug:0 withValue:45];
+@endverbatim
+
+The code section is followed by another standard paragraph.
+
+@param param The parameter.
+@param value The value.
+@return Returns some value.
+@exception NSException Thrown if something goes wrong.
+@warning @b Important: Use this method only for doing nothing. Because that's what it
+ does...
+@bug @b BUG: There's a strange bug in this method. And that is - it misses all the code! To
+ reproduce it, just follow these instructions: write another method in the class
+ interface and ommit the definition in the class implementation section.
+@see someOtherMethod:
+*/
++ (BOOL) thisMethodUsesWarningAndBug:(int) param withValue:(int) value;
+
@end
//////////////////////////////////////////////////////////////////////////////////////////
View
@@ -217,6 +217,13 @@ or more of the following options to actually produce something more readable...
* `--docset`: Generate documentation set (this will automatically enable xhtml as well!).
+XHTML output options
+--------------------
+
+* `--xhtml-bordered-issues`: Use bordered examples, warnings and bugs to make them
+ stand out of the rest a bit more. This also produces more Apple like documentation.
+
+
Documentation set related options
---------------------------------
@@ -299,6 +306,12 @@ line counterparts is:
* `DoxygenConfigFile` (String): `--doxyfile`
* `CreateXHTML` (Boolean): `--xhtml`
* `CreateDocSet` (Boolean): `--docset`
+* `XHTMLUseBorderedExamples` (Boolean): `--xhtml-bordered-issues` can be used to set
+ XHTMLUseBorderedExamples, XHTMLUseBorderedWarnings and XHTMLUseBorderedBugs in one
+ setting. There is no way to specify each separately over command line. There's also
+ no way to specify all three with a single setting in global parameters.
+* `XHTMLUseBorderedWarnings` (Boolean): see previous item.
+* `XHTMLUseBorderedBugs` (Boolean): see previous item.
* `DocSetBundleID` (String): `--docid`
* `DocSetBundleFeed` (String): `--docfeed`
* `DocSetSourcePlist` (String): `--docplist`
View
@@ -213,7 +213,31 @@ dl.parameterList dt {
dl.parameterList dd {
margin-left: 1.8em;
}
+
+.warning {
+ border: 1px solid #000;
+ background-color: #e6e6e6;
+ padding-right: 1em;
+ padding-left: 1em;
+ margin-bottom: 0.5em;
+ }
+
+.example {
+ border: 1px solid #c9d1d7;
+ background-color: #f1f5f9;
+ padding-right: 1em;
+ padding-left: 1em;
+ margin-bottom: 0.5em;
+ }
+.bug {
+ border: 1px solid #000;
+ background-color: #ffffcc;
+ padding-right: 1em;
+ padding-left: 1em;
+ margin-bottom: 0.5em;
+ }
+
/* -------------------------------------*/
/* --------->>>> =Tooltips <<<<---------*/
/* -------------------------------------*/
View
@@ -134,6 +134,8 @@ 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:
*/
- (void) appendBriefDescriptionToData:(NSMutableData*) data
fromItem:(id) item;
@@ -148,10 +150,27 @@ 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:
*/
- (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.
@@ -160,8 +179,11 @@ computer code, paragraphs, links etc. Note that this is the only place where the
data XML structure is exposed to the class.
@param data The data to append to.
-@param item The description paragraph which data to convert.
+@param item The description paragraph which data to convert. If @c nil nothing will happen.
@exception NSException Thrown if convertion fails.
+@see appendBriefDescriptionToData:fromItem:
+@see appendDetailedDescriptionToData:fromItem:
+@see appendDescriptionToData:fromParagraphs:
*/
- (void) appendDescriptionToData:(NSMutableData*) data
fromParagraph:(id) item;
Oops, something went wrong. Retry.

0 comments on commit 0a190cf

Please sign in to comment.