diff --git a/ChangeLog b/ChangeLog index a04dd17c5..98e0213fe 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,9 @@ +2001-10-15 Richard Frith-Macdonald + + * Tools/AGSOutput.m: Added new 'unit' pseudo-markup to permit + control over chapter layout for a chapter containing class, + category, or protocol documentation. + 2001-10-14 Fred Kiefer * Source/Unicode.m: diff --git a/Tools/AGSOutput.h b/Tools/AGSOutput.h index c5c0ca089..dabc42e49 100644 --- a/Tools/AGSOutput.h +++ b/Tools/AGSOutput.h @@ -40,9 +40,9 @@ - (BOOL) output: (NSDictionary*)d file: (NSString*)name; - (void) outputMethod: (NSDictionary*)d to: (NSMutableString*)str; - (void) outputUnit: (NSDictionary*)d to: (NSMutableString*)str; -- (void) reformat: (NSString*)str - withIndent: (unsigned)ind - to: (NSMutableString*)buf; +- (unsigned) reformat: (NSString*)str + withIndent: (unsigned)ind + to: (NSMutableString*)buf; - (NSArray*) split: (NSString*)str; @end diff --git a/Tools/AGSOutput.m b/Tools/AGSOutput.m index 180fb3f77..a1719f5cd 100644 --- a/Tools/AGSOutput.m +++ b/Tools/AGSOutput.m @@ -32,7 +32,7 @@ static BOOL snuggleEnd(NSString *t) } if (set == nil) { - set = [NSCharacterSet characterSetWithCharactersInString: @"]}).,;?!"]; + set = [NSCharacterSet characterSetWithCharactersInString: @"]}).,;"]; RETAIN(set); } return [set characterIsMember: [t characterAtIndex: 0]]; @@ -50,7 +50,16 @@ static BOOL snuggleStart(NSString *t) return [set characterIsMember: [t characterAtIndex: [t length] - 1]]; } - +/** + * + * The AGSOutput class + *

This is a really great class ... but it's not really reusable since it's + * far too special purpose.

+ * + *

Here is the afterword for the class.

+ * + * And finally, here is the actual class description ... outside the chapter. + */ @implementation AGSOutput - (void) dealloc @@ -536,21 +545,96 @@ static BOOL snuggleStart(NSString *t) NSString *name = [d objectForKey: @"Name"]; NSString *type = [d objectForKey: @"Type"]; NSDictionary *methods = [d objectForKey: @"Methods"]; + NSString *comment = [d objectForKey: @"Comment"]; NSArray *names; NSArray *protocols; NSString *tmp; + NSString *unit; + NSRange r; + unsigned ind; unsigned i; + unsigned j; - [str appendString: @" \n"]; + /* + * Make sure we have a 'unit' part and a class 'desc' part (comment) + * to be output. + */ + r = [comment rangeOfString: @""]; + if (comment != nil && r.length > 0) + { + unsigned pos = r.location; - [str appendString: @" "]; - [str appendString: @"Software documentation for the "]; - [str appendString: name]; - [str appendString: @" "]; - [str appendString: type]; - [str appendString: @"\n"]; + r = [comment rangeOfString: @""]; + if (r.length == 0 || r.location < pos) + { + NSLog(@"Unterminated in comment for %@", name); + return; + } + + if (pos == 0) + { + if (NSMaxRange(r) == [comment length]) + { + unit = comment; + comment = nil; + } + else + { + unit = [comment substringToIndex: NSMaxRange(r)]; + comment = [comment substringFromIndex: NSMaxRange(r)]; + } + } + else + { + if (NSMaxRange(r) == [comment length]) + { + unit = [comment substringFromIndex: pos]; + comment = [comment substringToIndex: pos]; + } + else + { + unsigned end = NSMaxRange(r); - [str appendString: @" <"]; + r = NSMakeRange(pos, end-pos); + unit = [comment substringWithRange: r]; + comment = [[comment substringToIndex: pos] + stringByAppendingString: [comment substringFromIndex: end]]; + } + } + unit = [unit stringByReplacingString: @"unit>" withString: @"chapter>"]; + } + else + { + unit = [NSString stringWithFormat: + @" \n Software documentation " + @"for the %@ %@\n \n", name, type]; + } + + /* + * Get the range of the location in the chapter where the class + * details should get substituted in. If there is nowhere marked, + * create a zero length range just before the end of the chapter. + */ + r = [unit rangeOfString: @""]; + if (r.length == 0) + { + r = [unit rangeOfString: @""]; + } + if (r.length == 0) + { + r = [unit rangeOfString: @""]; + r.length = 0; + } + + /* + * Output first part of chapter and note indentation. + */ + ind = [self reformat: [unit substringToIndex: r.location] + withIndent: 4 + to: str]; + + for (j = 0; j < ind; j++) [str appendString: @" "]; + [str appendString: @"<"]; [str appendString: type]; [str appendString: @" name=\""]; if ([type isEqual: @"category"] == YES) @@ -576,7 +660,9 @@ static BOOL snuggleStart(NSString *t) } [str appendString: @"\">\n"]; - [str appendString: @" "]; + ind += 2; + for (j = 0; j < ind; j++) [str appendString: @" "]; + [str appendString: @""]; [str appendString: [d objectForKey: @"Declared"]]; [str appendString: @"\n"]; @@ -585,19 +671,21 @@ static BOOL snuggleStart(NSString *t) { for (i = 0; i < [protocols count]; i++) { - [str appendString: @" "]; + for (j = 0; j < ind; j++) [str appendString: @" "]; + [str appendString: @""]; [str appendString: [protocols objectAtIndex: i]]; [str appendString: @"\n"]; } } - [str appendString: @" \n"]; - tmp = [d objectForKey: @"Comment"]; - if (tmp != nil) + for (j = 0; j < ind; j++) [str appendString: @" "]; + [str appendString: @"\n"]; + if (comment != nil) { - [self reformat: tmp withIndent: 10 to: str]; + [self reformat: comment withIndent: ind + 2 to: str]; } - [str appendString: @" \n"]; + for (j = 0; j < ind; j++) [str appendString: @" "]; + [str appendString: @"\n"]; names = [[methods allKeys] sortedArrayUsingSelector: @selector(compare:)]; for (i = 0; i < [names count]; i++) @@ -607,15 +695,23 @@ static BOOL snuggleStart(NSString *t) [self outputMethod: [methods objectForKey: mName] to: str]; } - [str appendString: @" \n"]; - [str appendString: @" \n"]; + + /* + * Output tail end of chapter. + */ + [self reformat: [unit substringFromIndex: NSMaxRange(r)] + withIndent: ind + to: str]; } -- (void) reformat: (NSString*)str - withIndent: (unsigned)ind - to: (NSMutableString*)buf +- (unsigned) reformat: (NSString*)str + withIndent: (unsigned)ind + to: (NSMutableString*)buf { CREATE_AUTORELEASE_POOL(arp); unsigned l = [str length]; @@ -652,7 +748,7 @@ static BOOL snuggleStart(NSString *t) if (r.length == 0) { NSLog(@"unterminated "); - return; + return ind; } tmp = [str substringWithRange: NSMakeRange(i, NSMaxRange(r) - i)]; [buf appendString: tmp]; @@ -737,6 +833,7 @@ static BOOL snuggleStart(NSString *t) } } RELEASE(arp); + return ind; } - (NSArray*) split: (NSString*)str diff --git a/Tools/autogsdoc.m b/Tools/autogsdoc.m index a328d9dd6..0d6bdd9e0 100644 --- a/Tools/autogsdoc.m +++ b/Tools/autogsdoc.m @@ -68,7 +68,7 @@ <chapter> Placed immediately before any generated class documentation ... intended to be used to provide overall description of how the - code bing documented works. + code being documented works.
 <copy> Copyright of the content of the document ... placed in the head @@ -88,6 +88,16 @@ If this is omitted the tool will generate a (probably poor) title of its own. + + NBThis markup may be used within + class, category, or protocol documentation ... if so, it is + extracted and wrapped round the rest of the documentation for + the class as the classes chapter. + The rest of the class documentation is normally + inserted at the end of the chapter, but may instead be sbstituted + in in place of the <unit /> pseudo-element within the + <chapter> element. + <version> Version identifier of the document ... placed in the head of the gsdoc output. If this is omitted the tool will try to