diff --git a/ChangeLog b/ChangeLog index 1a92da916..1d64cb8e1 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +2001-12-15 Richard Frith-Macdonald + + * Tools/AGSHtml.h: new methods for cleaner indexing. + * Tools/AGSHtml.m: new methods for cleaner indexing. + * Tools/AGSParser.m: minor bugfixes. + * Tools/GNUmakefile: Build autogsdoc documentation using autogsdoc. + * Tools/autogsdoc.m: Fix minor dependency error. + * Tools/gsdoc-0_6_7.dtd: Fix ivar support + 2001-12-13 Adam Fedor * Tools/pl2link.m: New file (from FredKiefer@gmx.de). diff --git a/Tools/AGSHtml.h b/Tools/AGSHtml.h index c6d3f5a16..3518ac60d 100644 --- a/Tools/AGSHtml.h +++ b/Tools/AGSHtml.h @@ -39,6 +39,16 @@ } - (void) decIndent; - (void) incIndent; +- (NSString*) makeAnchor: (NSString*)r + ofType: (NSString*)t + name: (NSString*)n; +- (NSString*) makeLink: (NSString*)r + ofType: (NSString*)t + isRef: (BOOL)f; +- (NSString*) makeLink: (NSString*)r + ofType: (NSString*)t + inUnit: (NSString*)u + isRef: (BOOL)f; - (NSString*) outputDocument: (GSXMLNode*)node; - (void) outputNode: (GSXMLNode*)node to: (NSMutableString*)buf; - (void) outputNodeList: (GSXMLNode*)node to: (NSMutableString*)buf; diff --git a/Tools/AGSHtml.m b/Tools/AGSHtml.m index 1bdc695b5..6e13a3449 100644 --- a/Tools/AGSHtml.m +++ b/Tools/AGSHtml.m @@ -104,6 +104,170 @@ static NSMutableSet *textNodes = nil; return self; } +/** + * Calls -makeLink:ofType:isRef: or -makeLink:ofType:inUnit:isRef: to + * create the first part of an anchor, and fills in the text content + * of the anchor with n (the specified name). Returns an entire anchor + * string as a result.
+ * This method is used to create all the anchors in the html output. + */ +- (NSString*) makeAnchor: (NSString*)r + ofType: (NSString*)t + name: (NSString*)n +{ + NSString *s; + + if (n == nil) + { + n = @""; + } + if ([t isEqualToString: @"method"] || [t isEqualToString: @"ivariable"]) + { + s = [self makeLink: r ofType: t inUnit: nil isRef: NO]; + } + else + { + s = [self makeLink: r ofType: t isRef: NO]; + } + if (s != nil) + { + n = [s stringByAppendingFormat: @"%@", n]; + } + return n; +} + +/** + * Make a link for the element r with the specified type. Only the start of + * the html element is returned (<a ...>). + * If the boolean f is YES, then the link is a reference to somewhere, + * and the method will return nil if the destination is not found in the index. + * If f is NO, then the link is an anchor for some element being output, and + * the method is guaranteed to succeed and return the link. + */ +- (NSString*) makeLink: (NSString*)r + ofType: (NSString*)t + isRef: (BOOL)f +{ + NSString *s; + NSString *kind = (f == YES) ? @"href" : @"name"; + + if (f == NO || (s = [localRefs globalRef: r type: t]) != nil) + { + s = [NSString stringWithFormat: @"", + kind, t, r]; + } + else if ((s = [globalRefs globalRef: r type: t]) != nil) + { + s = [s stringByAppendingPathExtension: @"html"]; + s = [NSString stringWithFormat: @"", + kind, s, t, r]; + } + return s; +} + +/** + * Make a link for the element r, with the specified type t, + * in a particular unit u. Only the start of + * the html element is returned (<a ...>).
+ * If the boolean f is YES, then the link is a reference to somewhere, + * otherwise the link is an anchor for some element being output.
+ * The method will try to infer the unit in which the emement was + * defined if the value of u is nil.
+ * If there is an error, the method returns nil. + */ +- (NSString*) makeLink: (NSString*)r + ofType: (NSString*)t + inUnit: (NSString*)u + isRef: (BOOL)f +{ + NSString *s; + BOOL isLocal = YES; + NSString *kind = (f == YES) ? @"href" : @"name"; + + /* + * No unit specified ... try to infer it. + */ + if (u == nil) + { + /* + * If we are currently inside a class, category, or protocol + * we see if the required item exists in that unit and if so, + * we assume that this is the unit to be used. + */ + if (unit != nil) + { + s = [localRefs unitRef: r type: t unit: unit]; + if (s != nil) + { + u = unit; + } + } + /* + * If we are making a reference, and we have not found it in the + * current unit, we check all known references to see if the item + * is uniquely documented somewhere. + */ + if (u == nil && f == YES) + { + NSDictionary *d; + + d = [localRefs unitRef: r type: t]; + if ([d count] == 0) + { + isLocal = NO; + d = [globalRefs unitRef: r type: t]; + } + if ([d count] == 1) + { + /* + * Record the class where the item is documented + * and the file where that documentation occurs. + */ + u = [[d allKeys] objectAtIndex: 0]; + s = [d objectForKey: u]; + } + } + } + else + { + /* + * Simply look up the reference. + */ + s = [localRefs unitRef: r type: t unit: u]; + if (s == nil && f == YES) + { + isLocal = NO; + s = [globalRefs unitRef: r type: t unit: u]; + } + } + + /** + * There are only two types of unit specific element ... methods + * and instance variables. The names within a unit are unique + * since you can't have two methods or two variables with the + * same name in a unit, and all method names contain either a + * a plus or minus as a prefix, while no variables do.
+ * This means that we do not need to incorporate any type + * information into anchors and references for methods or + * instance varibales. + */ + if (s != nil) + { + if (isLocal == YES) + { + s = [NSString stringWithFormat: @"", + kind, u, r]; + } + else + { + s = [s stringByAppendingPathExtension: @"html"]; + s = [NSString stringWithFormat: @"", + kind, s, u, r]; + } + } + return s; +} + - (NSString*) outputDocument: (GSXMLNode*)node { NSMutableString *buf; @@ -163,11 +327,16 @@ static NSMutableSet *textNodes = nil; { NSString *name = [prop objectForKey: @"name"]; NSString *cls = [prop objectForKey: @"class"]; + NSString *s; - cls = [self typeRef: cls]; + [buf appendString: indent]; + [buf appendString: @"

"]; + [buf appendString: [self typeRef: cls]]; + [buf appendString: @"("]; unit = [NSString stringWithFormat: @"%@(%@)", cls, name]; - [buf appendFormat: @"

%@(%@)

\n", - unit, cls, name]; + s = [self makeAnchor: unit ofType: @"category" name: name]; + [buf appendString: s]; + [buf appendString: @")\n"]; [self outputUnit: node to: buf]; unit = nil; } @@ -182,20 +351,17 @@ static NSMutableSet *textNodes = nil; NSString *sup = [prop objectForKey: @"super"]; unit = name; + [buf appendString: indent]; + [buf appendString: @"

"]; + [buf appendString: + [self makeAnchor: name ofType: @"class" name: name]]; sup = [self typeRef: sup]; - if (sup == nil) + if (sup != nil) { - /* - * This is a root class. - */ - [buf appendFormat: @"

%@

\n", - unit, name]; - } - else - { - [buf appendFormat: @"

%@ : %@

\n", - unit, name, sup]; + [buf appendString: @" : "]; + [buf appendString: sup]; } + [buf appendString: @"\n"]; [self outputUnit: node to: buf]; unit = nil; } @@ -259,7 +425,7 @@ static NSMutableSet *textNodes = nil; { val = text; } - [buf appendFormat: @"", val]; + [buf appendString: [self makeAnchor: val ofType: @"label" name: @""]]; } else if ([name isEqual: @"example"] == YES) { @@ -447,6 +613,12 @@ static NSMutableSet *textNodes = nil; [buf appendString: heading]; [buf appendString: @">\n"]; } + else if ([name isEqual: @"ivar"] == YES) // %phrase + { + [buf appendString: @""]; + [self outputText: children to: buf]; + [buf appendString: @""]; + } else if ([name isEqual: @"ivariable"] == YES) { NSString *tmp = [prop objectForKey: @"name"]; @@ -464,9 +636,8 @@ NSLog(@"Element '%@' not implemented", name); // FIXME { val = text; } - [buf appendFormat: @"", val]; - [self outputText: children to: buf]; - [buf appendString: @""]; + [buf appendString: + [self makeAnchor: val ofType: @"label" name: text]]; } else if ([name isEqual: @"method"] == YES) { @@ -551,12 +722,25 @@ NSLog(@"Element '%@' not implemented", name); // FIXME } if ([sel length] > 1) { + NSString *s; + /* * Output selector heading. */ [buf appendString: indent]; - [buf appendFormat: @"

%@

\n", - unit, sel, [sel substringFromIndex: 1]]; + [buf appendString: @"

"]; + s = [self makeLink: sel ofType: @"method" inUnit: nil isRef: NO]; + if (s == nil) + { + [buf appendString: s]; + [buf appendString: [sel substringFromIndex: 1]]; + [buf appendString: @""]; + } + else + { + [buf appendString: [sel substringFromIndex: 1]]; + } + [buf appendString: @"

\n"]; [buf appendString: indent]; [buf appendString: str]; [buf appendString: @";
\n"]; @@ -620,120 +804,26 @@ NSLog(@"Element '%@' not implemented", name); // FIXME { NSString *type = [prop objectForKey: @"type"]; NSString *r = [prop objectForKey: @"id"]; - NSString *f = nil; - BOOL isLocal = YES; + NSString *s; - if ([type isEqual: @"method"] || [type isEqual: @"variable"]) + if ([type isEqual: @"method"] || [type isEqual: @"ivariable"]) { - NSString *c = [prop objectForKey: @"class"]; - - /* - * No class specified ... try to infer it. - */ - if (c == nil) - { - /* - * If we are currently inside a class, category, or protocol - * we see if the required item exists in that unit and if so, - * we assume that we need a local reference. - */ - if (unit != nil) - { - f = [localRefs unitRef: r type: type unit: unit]; - if (f == nil) - { - f = [globalRefs unitRef: r type: type unit: unit]; - if (f != nil) - { - isLocal = NO; - c = unit; - } - } - else - { - c = unit; - } - } - /* - * If we have not found it in the current unit, we check - * all known references to see if the item is uniquely - * documented somewhere. - */ - if (c == nil) - { - NSDictionary *d; - - d = [localRefs unitRef: r type: type]; - if ([d count] == 0) - { - isLocal = NO; - d = [globalRefs unitRef: r type: type]; - } - if ([d count] == 1) - { - /* - * Record the class where the item is documented - * and the file where that documentation occurs. - */ - c = [[d allKeys] objectAtIndex: 0]; - f = [d objectForKey: c]; - } - } - } - else - { - /* - * Simply look up the reference. - */ - f = [localRefs unitRef: r type: type unit: c]; - if (f == nil) - { - isLocal = NO; - f = [globalRefs unitRef: r type: type unit: c]; - } - } - - if (f != nil) - { - f = [f stringByAppendingPathExtension: @"html"]; - if (isLocal == YES) - { - [buf appendFormat: @"", c, r]; - } - else - { - [buf appendFormat: @"", f, c, r]; - } - } + s = [prop objectForKey: @"class"]; + s = [self makeLink: r ofType: type inUnit: s isRef: YES]; } else { - f = [localRefs globalRef: r type: type]; - if (f == nil) - { - isLocal = NO; - f = [globalRefs globalRef: r type: type]; - } - if (f != nil) - { - f = [f stringByAppendingPathExtension: @"html"]; - if (isLocal == YES) - { - [buf appendFormat: @"", type, r]; - } - else - { - [buf appendFormat: @"", f, type, r]; - } - } + s = [self makeLink: r ofType: type isRef: YES]; } - if (f == nil) + if (s == nil) { NSLog(@"ref '%@' not found for %@", r, type); [self outputText: [node children] to: buf]; + [buf appendString: @"\n"]; } else { + [buf appendString: s]; [self outputText: [node children] to: buf]; [buf appendString: @"\n"]; } @@ -743,8 +833,11 @@ NSLog(@"Element '%@' not implemented", name); // FIXME NSString *name = [prop objectForKey: @"name"]; unit = [NSString stringWithFormat: @"(%@)", name]; - [buf appendFormat: - @"

<%@>

\n", unit, name]; + [buf appendString: indent]; + [buf appendString: @"

"]; + [buf appendString: + [self makeAnchor: name ofType: @"protocol" name: name]]; + [buf appendString: @"

\n"]; [self outputUnit: node to: buf]; unit = nil; } @@ -753,8 +846,7 @@ NSLog(@"Element '%@' not implemented", name); // FIXME || [name isEqual: @"EOModel"] == YES || [name isEqual: @"function"] == YES || [name isEqual: @"macro"] == YES - || [name isEqual: @"type"] == YES - || [name isEqual: @"variable"] == YES) + || [name isEqual: @"type"] == YES) { NSString *tmp = [prop objectForKey: @"name"]; @@ -790,11 +882,15 @@ NSLog(@"Element '%@' not implemented", name); // FIXME else if ([name isEqual: @"type"] == YES) { NSString *n = [prop objectForKey: @"name"]; + NSString *s; node = [node children]; + s = [NSString stringWithFormat: @"typedef %@ %@", [node content], n]; [buf appendString: indent]; - [buf appendFormat: @"

typedef %@ %@

", - n, [node content], n]; + [buf appendString: @"

"]; + [buf appendString: + [self makeAnchor: n ofType: @"type" name: s]]; + [buf appendString: @"

\n"]; node = [node next]; if (node != nil && [[node name] isEqual: @"declared"] == YES) @@ -834,6 +930,10 @@ NSLog(@"Element '%@' not implemented", name); // FIXME [self outputText: children to: buf]; [buf appendString: @""]; } + else if ([name isEqual: @"variable"] == YES) + { +NSLog(@"Element '%@' not implemented", name); // FIXME + } else { GSXMLNode *tmp; @@ -1124,15 +1224,10 @@ NSLog(@"Element '%@' not implemented", name); // FIXME t = [t stringByTrimmingSpaces]; n = [NSString stringWithFormat: @"(%@)", t]; - if ((s = [localRefs globalRef: n type: @"protocol"]) != nil) + s = [self makeLink: n ofType: @"protocol" isRef: YES]; + if (s != nil) { - t = [NSString stringWithFormat: @"%@", n, t]; - } - else if ((s = [globalRefs globalRef: t type: @"protocol"]) != nil) - { - s = [s stringByAppendingPathExtension: @"html"]; - t = [NSString stringWithFormat: @"%@", - s, n, t]; + t = [s stringByAppendingString: @"t"]; } return t; } @@ -1186,28 +1281,15 @@ NSLog(@"Element '%@' not implemented", name); // FIXME } t = [orig substringWithRange: NSMakeRange(start, end - start)]; - if ((s = [localRefs globalRef: t type: @"type"]) != nil) + s = [self makeLink: t ofType: @"type" isRef: YES]; + if (s == nil) { - s = [NSString stringWithFormat: @"%@", t, t]; - } - else if ((s = [localRefs globalRef: t type: @"class"]) != nil) - { - s = [NSString stringWithFormat: @"%@", t, t]; - } - else if ((s = [globalRefs globalRef: t type: @"type"]) != nil) - { - s = [s stringByAppendingPathExtension: @"html"]; - s = [NSString stringWithFormat: @"%@", - s, t, t]; - } - else if ((s = [globalRefs globalRef: t type: @"class"]) != nil) - { - s = [s stringByAppendingPathExtension: @"html"]; - s = [NSString stringWithFormat: @"%@", - s, t, t]; + s = [self makeLink: t ofType: @"class" isRef: YES]; } + if (s != nil) { + s = [s stringByAppendingFormat: @"%@", t]; if ([orig length] == [t length]) { return s; @@ -1216,5 +1298,6 @@ NSLog(@"Element '%@' not implemented", name); // FIXME } return orig; } + @end diff --git a/Tools/AGSParser.m b/Tools/AGSParser.m index 63ea89089..6f9b75b7e 100644 --- a/Tools/AGSParser.m +++ b/Tools/AGSParser.m @@ -1279,6 +1279,9 @@ fail: * comments (with an additional asterisk after the start of the block * comment) and extracts their contents, accumulating them into the * 'comment' instance variable.
+ * When the data provided by a comment is appended to the data + * stored in the 'comment' instance variable, a line break (<br />)is + * automatically forced to separate it from the proceding info.
* In addition, the first extracted documentation is checked for the * prsence of file header markup, which is extracted into the 'info' * dictionary. @@ -1392,7 +1395,7 @@ fail: tmp = [NSString stringWithCharacters: start length: end - start]; if (comment != nil) { - tmp = [comment stringByAppendingString: tmp]; + tmp = [comment stringByAppendingFormat: @"
\n%@", tmp]; } ASSIGN(comment, tmp); } diff --git a/Tools/GNUmakefile b/Tools/GNUmakefile index 1c9a6bd79..b75e0c617 100644 --- a/Tools/GNUmakefile +++ b/Tools/GNUmakefile @@ -61,12 +61,19 @@ plmerge_OBJC_FILES = plmerge.m plparse_OBJC_FILES = plparse.m sfparse_OBJC_FILES = sfparse.m pl2link_OBJC_FILES = pl2link.m - locale_alias_OBJC_FILES = locale_alias.m -SOURCES = gdomap.c gdnc.m defaults.m dread.m dremove.m dwrite.m +DOCUMENT_NAME = autogsdoc -HEADERS = gdomap.h gdnc.h +# Files to be documented +autogsdoc_AGSDOC_FILES = autogsdoc.m \ + AGSParser.h AGSOutput.h AGSIndex.h AGSHtml.h + +SOURCES = gdomap.c gdnc.m defaults.m dread.m dremove.m dwrite.m \ + autogsdoc.m AGSParser.m AGSOutput.m AGSIndex.m AGSHtml.m + +HEADERS = gdomap.h gdnc.h \ + AGSParser.h AGSOutput.h AGSIndex.h AGSHtml.h DIST_FILES = GNUmakefile Makefile.preamble Makefile.postamble \ $(SOURCES) $(HEADERS) @@ -78,6 +85,7 @@ include Makefile.preamble include $(GNUSTEP_MAKEFILES)/ctool.make include $(GNUSTEP_MAKEFILES)/tool.make include $(GNUSTEP_MAKEFILES)/test-tool.make +include $(GNUSTEP_MAKEFILES)/documentation.make include Makefile.postamble diff --git a/Tools/autogsdoc.m b/Tools/autogsdoc.m index 9b3a1e818..47c77ea6a 100644 --- a/Tools/autogsdoc.m +++ b/Tools/autogsdoc.m @@ -525,7 +525,7 @@ main(int argc, char **argv, char **env) NSDate *d; d = [attrs objectForKey: NSFileModificationDate]; - if (sDate == nil || [d earlierDate: sDate] == d) + if (sDate == nil || [d earlierDate: sDate] == sDate) { sDate = d; AUTORELEASE(RETAIN(sDate)); diff --git a/Tools/gsdoc-0_6_7.dtd b/Tools/gsdoc-0_6_7.dtd index d83bf5c1a..d29aa39ee 100644 --- a/Tools/gsdoc-0_6_7.dtd +++ b/Tools/gsdoc-0_6_7.dtd @@ -54,7 +54,7 @@ - + @@ -149,7 +149,7 @@ @@ -488,7 +488,7 @@