diff --git a/ChangeLog b/ChangeLog index ddba7a12a..69d8b57d2 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,6 +1,8 @@ 2002-06-09 Richard Frith-Macdonald * Source/NSObject.m: Implemented and documented -className + * Tools/AGSOutput.m: When Verbose = YES log all documentable + entities for which no comment text was found. 2002-06-06 Adam Fedor diff --git a/Headers/gnustep/base/NSString.h b/Headers/gnustep/base/NSString.h index 76f7eadc7..9961b4a04 100644 --- a/Headers/gnustep/base/NSString.h +++ b/Headers/gnustep/base/NSString.h @@ -258,7 +258,7 @@ enum { locale: (NSDictionary*)locale, ...; - (id) initWithFormat: (NSString*)format locale: (NSDictionary*)locale - arguments: (va_list)arg_list; + arguments: (va_list)argList; - (id) initWithUTF8String: (const char *)bytes; - (id) initWithContentsOfURL: (NSURL*)url; - (NSString*) substringWithRange: (NSRange)aRange; diff --git a/Source/NSString.m b/Source/NSString.m index a1a6247bd..8eced104c 100644 --- a/Source/NSString.m +++ b/Source/NSString.m @@ -754,14 +754,14 @@ handle_printf_atsign (FILE *stream, } - (id) initWithFormat: (NSString*)format - arguments: (va_list)arg_list + arguments: (va_list)argList { - return [self initWithFormat: format locale: nil arguments: arg_list]; + return [self initWithFormat: format locale: nil arguments: argList]; } - (id) initWithFormat: (NSString*)format locale: (NSDictionary*)locale - arguments: (va_list)arg_list + arguments: (va_list)argList { FormatBuf_t f; unichar *fmt; @@ -775,7 +775,7 @@ handle_printf_atsign (FILE *stream, f.buf = NSZoneMalloc(f.z, 100*sizeof(unichar)); f.len = 0; f.size = 100; - GSFormat(&f, fmt, arg_list, locale); + GSFormat(&f, fmt, argList, locale); objc_free(fmt); // don't use noCopy because f.size > f.len! self = [self initWithCharacters: f.buf length: f.len]; @@ -787,7 +787,7 @@ handle_printf_atsign (FILE *stream, /* xxx Change this when we have non-CString classes */ - (id) initWithFormat: (NSString*)format locale: (NSDictionary*)locale - arguments: (va_list)arg_list + arguments: (va_list)argList { #if defined(HAVE_VSPRINTF) || defined(HAVE_VASPRINTF) const char *format_cp = [format lossyCString]; @@ -832,7 +832,7 @@ handle_printf_atsign (FILE *stream, *atsign_pos = '\0'; /* Print the part before the '%@' */ printed_local_len = VASPRINTF_LENGTH (vasprintf (&buf_l, - format_to_go, arg_list)); + format_to_go, argList)); if(buf_l) { if(avail_len < printed_local_len+1) @@ -879,21 +879,21 @@ handle_printf_atsign (FILE *stream, for this */ case 'd': case 'i': case 'o': case 'x': case 'X': case 'u': case 'c': - va_arg(arg_list, int); + va_arg(argList, int); break; case 's': if (*(spec_pos - 1) == '*') - va_arg(arg_list, int*); - va_arg(arg_list, char*); + va_arg(argList, int*); + va_arg(argList, char*); break; case 'f': case 'e': case 'E': case 'g': case 'G': - va_arg(arg_list, double); + va_arg(argList, double); break; case 'p': - va_arg(arg_list, void*); + va_arg(argList, void*); break; case 'n': - va_arg(arg_list, int*); + va_arg(argList, int*); break; #endif /* NOT powerpc */ case '\0': @@ -903,7 +903,7 @@ handle_printf_atsign (FILE *stream, format_to_go = spec_pos+1; } /* Get a C-string (char*) from the String object, and print it. */ - cstring = [[(id) va_arg (arg_list, id) description] lossyCString]; + cstring = [[(id) va_arg (argList, id) description] lossyCString]; if (!cstring) cstring = ""; cstring_len = strlen(cstring); @@ -925,7 +925,7 @@ handle_printf_atsign (FILE *stream, } /* Print the rest of the string after the last `%@'. */ printed_local_len = VASPRINTF_LENGTH (vasprintf (&buf_l, - format_to_go, arg_list)); + format_to_go, argList)); if(buf_l) { if(avail_len < printed_local_len+1) @@ -957,7 +957,7 @@ handle_printf_atsign (FILE *stream, #else /* HAVE_VSPRINTF */ /* The available libc has `register_printf_function()', so the `%@' printf directive is handled by printf and friends. */ - printed_len = VASPRINTF_LENGTH (vasprintf (&buf, format_cp, arg_list)); + printed_len = VASPRINTF_LENGTH (vasprintf (&buf, format_cp, argList)); if(!buf) { @@ -1006,7 +1006,7 @@ handle_printf_atsign (FILE *stream, *atsign_pos = '\0'; /* Print the part before the '%@' */ printed_len += VSPRINTF_LENGTH (vsprintf (buf+printed_len, - format_to_go, arg_list)); + format_to_go, argList)); /* Skip arguments used in last vsprintf(). */ while ((formatter_pos = strchr(format_to_go, '%'))) { @@ -1026,21 +1026,21 @@ handle_printf_atsign (FILE *stream, for this */ case 'd': case 'i': case 'o': case 'x': case 'X': case 'u': case 'c': - (void)va_arg(arg_list, int); + (void)va_arg(argList, int); break; case 's': if (*(spec_pos - 1) == '*') - (void)va_arg(arg_list, int*); - (void)va_arg(arg_list, char*); + (void)va_arg(argList, int*); + (void)va_arg(argList, char*); break; case 'f': case 'e': case 'E': case 'g': case 'G': - (void)va_arg(arg_list, double); + (void)va_arg(argList, double); break; case 'p': - (void)va_arg(arg_list, void*); + (void)va_arg(argList, void*); break; case 'n': - (void)va_arg(arg_list, int*); + (void)va_arg(argList, int*); break; #endif /* NOT powerpc */ case '\0': @@ -1050,7 +1050,7 @@ handle_printf_atsign (FILE *stream, format_to_go = spec_pos+1; } /* Get a C-string (char*) from the String object, and print it. */ - cstring = [[(id) va_arg (arg_list, id) description] lossyCString]; + cstring = [[(id) va_arg (argList, id) description] lossyCString]; if (!cstring) cstring = ""; strcat (buf+printed_len, cstring); @@ -1060,12 +1060,12 @@ handle_printf_atsign (FILE *stream, } /* Print the rest of the string after the last `%@'. */ printed_len += VSPRINTF_LENGTH (vsprintf (buf+printed_len, - format_to_go, arg_list)); + format_to_go, argList)); } #else /* The available libc has `register_printf_function()', so the `%@' printf directive is handled by printf and friends. */ - printed_len = VSPRINTF_LENGTH (vsprintf (buf, format_cp, arg_list)); + printed_len = VSPRINTF_LENGTH (vsprintf (buf, format_cp, argList)); #endif /* !HAVE_REGISTER_PRINTF_FUNCTION */ /* Raise an exception if we overran our buffer. */ diff --git a/Tools/AGSOutput.h b/Tools/AGSOutput.h index 4116d694a..1388fff07 100644 --- a/Tools/AGSOutput.h +++ b/Tools/AGSOutput.h @@ -32,8 +32,12 @@ NSCharacterSet *spaces; // All blank characters NSCharacterSet *spacenl; // Blanks excluding newline NSArray *args; // Not retained. + BOOL verbose; } +- (NSString*) checkComment: (NSString*)comment + unit: (NSString*)unit + info: (NSDictionary*)d; - (unsigned) fitWords: (NSArray*)a from: (unsigned)start to: (unsigned)end @@ -44,7 +48,9 @@ kind: (NSString*)kind to: (NSMutableString*)str; - (void) outputFunction: (NSDictionary*)d to: (NSMutableString*)str; -- (void) outputInstanceVariable: (NSDictionary*)d to: (NSMutableString*)str; +- (void) outputInstanceVariable: (NSDictionary*)d + to: (NSMutableString*)str + for: (NSString*)unit; - (void) outputMethod: (NSDictionary*)d to: (NSMutableString*)str for: (NSString*)unit; @@ -52,6 +58,7 @@ - (unsigned) reformat: (NSString*)str withIndent: (unsigned)ind to: (NSMutableString*)buf; +- (void) setVerbose: (BOOL)flag; - (NSArray*) split: (NSString*)str; @end #endif diff --git a/Tools/AGSOutput.m b/Tools/AGSOutput.m index aee2f064b..394d42670 100644 --- a/Tools/AGSOutput.m +++ b/Tools/AGSOutput.m @@ -74,6 +74,39 @@ static BOOL snuggleStart(NSString *t) */ @implementation AGSOutput +- (NSString*) checkComment: (NSString*)comment + unit: (NSString*)unit + info: (NSDictionary*)d +{ + if ([comment length] == 0) + { + comment = @"Description forthcoming."; + if (verbose == YES) + { + NSString *name = [d objectForKey: @"Name"]; + NSString *type = [d objectForKey: @"Type"]; + + if (unit == nil) + { + NSLog(@"No comments for %@ %@", type, name); + } + else + { + if ([d objectForKey: @"ReturnType"] != nil) + { + NSLog(@"No comments for [%@ %@]", unit, name); + } + else + { + NSLog(@"No comments for instance variable %@ in %@", + name, unit); + } + } + } + } + return comment; +} + - (void) dealloc { DESTROY(identifier); @@ -623,10 +656,7 @@ static BOOL snuggleStart(NSString *t) } [str appendString: @" \n"]; - if ([comment length] == 0) - { - comment = @"Description forthcoming."; - } + comment = [self checkComment: comment unit: nil info: d]; [self reformat: comment withIndent: 10 to: str]; [str appendString: @" \n"]; if (standards != nil) @@ -768,10 +798,7 @@ static BOOL snuggleStart(NSString *t) } [str appendString: @" \n"]; - if ([comment length] == 0) - { - comment = @"Description forthcoming."; - } + comment = [self checkComment: comment unit: nil info: d]; [self reformat: comment withIndent: 10 to: str]; [str appendString: @" \n"]; if (standards != nil) @@ -785,7 +812,9 @@ static BOOL snuggleStart(NSString *t) /** * Output the gsdoc code for an instance variable. */ -- (void) outputInstanceVariable: (NSDictionary*)d to: (NSMutableString*)str +- (void) outputInstanceVariable: (NSDictionary*)d + to: (NSMutableString*)str + for: (NSString*)unit { NSString *type = [d objectForKey: @"Type"]; NSString *validity = [d objectForKey: @"Validity"]; @@ -805,10 +834,7 @@ static BOOL snuggleStart(NSString *t) [str appendString: @"\">\n"]; [str appendString: @" \n"]; - if ([comment length] == 0) - { - comment = @"Description forthcoming."; - } + comment = [self checkComment: comment unit: unit info: d]; [self reformat: comment withIndent: 12 to: str]; [str appendString: @" \n"]; if (standards != nil) @@ -981,10 +1007,7 @@ static BOOL snuggleStart(NSString *t) } [str appendString: @" \n"]; - if ([comment length] == 0) - { - comment = @"Description forthcoming."; - } + comment = [self checkComment: comment unit: unit info: d]; [self reformat: comment withIndent: 12 to: str]; [str appendString: @" \n"]; if (standards != nil) @@ -999,8 +1022,9 @@ static BOOL snuggleStart(NSString *t) { NSString *name = [d objectForKey: @"Name"]; NSString *type = [d objectForKey: @"Type"]; - NSDictionary *methods = [d objectForKey: @"Methods"]; - NSDictionary *ivars = [d objectForKey: @"InstanceVariables"]; + NSString *kind = type; + NSMutableDictionary *methods = [d objectForKey: @"Methods"]; + NSMutableDictionary *ivars = [d objectForKey: @"InstanceVariables"]; NSString *comment = [d objectForKey: @"Comment"]; NSString *unitName = nil; NSArray *names; @@ -1015,7 +1039,27 @@ static BOOL snuggleStart(NSString *t) if ([[d objectForKey: @"Implemented"] isEqual: @"YES"] == NO) { - NSLog(@"Warning ... unit %@ is not implemented where expected", name); + if ([name hasPrefix: @"NSObject("] == YES) + { + NSEnumerator *e = [methods objectEnumerator]; + NSMutableDictionary *m; + + /* + * Assume an unimplemented category of NSObject is an + * informal protocol, and stop warnings being issued + * about unimplemented methods. + */ + unitName = name; + kind = @"informal protocol"; + while ((m = [e nextObject]) != nil) + { + [m setObject: @"YES" forKey: @"Implemented"]; + } + } + else + { + NSLog(@"Warning ... unit %@ is not implemented where expected", name); + } } else { @@ -1104,7 +1148,7 @@ static BOOL snuggleStart(NSString *t) { unit = [NSString stringWithFormat: @" \n Software documentation " - @"for the %@ %@\n \n", name, type]; + @"for the %@ %@\n \n", name, kind]; } /* @@ -1177,10 +1221,7 @@ static BOOL snuggleStart(NSString *t) for (j = 0; j < ind; j++) [str appendString: @" "]; [str appendString: @"\n"]; - if ([comment length] == 0) - { - comment = @"Description forthcoming."; - } + comment = [self checkComment: comment unit: nil info: d]; [self reformat: comment withIndent: ind + 2 to: str]; for (j = 0; j < ind; j++) [str appendString: @" "]; [str appendString: @"\n"]; @@ -1190,7 +1231,9 @@ static BOOL snuggleStart(NSString *t) { NSString *vName = [names objectAtIndex: i]; - [self outputInstanceVariable: [ivars objectForKey: vName] to: str]; + [self outputInstanceVariable: [ivars objectForKey: vName] + to: str + for: unitName]; } names = [[methods allKeys] sortedArrayUsingSelector: @selector(compare:)]; @@ -1348,6 +1391,11 @@ static BOOL snuggleStart(NSString *t) return ind; } +- (void) setVerbose: (BOOL)flag +{ + verbose = flag; +} + - (NSArray*) split: (NSString*)str { NSMutableArray *a = [NSMutableArray arrayWithCapacity: 128]; diff --git a/Tools/AGSParser.m b/Tools/AGSParser.m index d43f17025..869b36b7f 100644 --- a/Tools/AGSParser.m +++ b/Tools/AGSParser.m @@ -731,10 +731,6 @@ { [d setObject: comment forKey: @"Comment"]; } - if (verbose == YES) - { - [self log: @"parse '%@'", d]; - } DESTROY(comment); } diff --git a/Tools/autogsdoc.m b/Tools/autogsdoc.m index 7f87234da..d3ada5ff2 100644 --- a/Tools/autogsdoc.m +++ b/Tools/autogsdoc.m @@ -543,6 +543,7 @@ main(int argc, char **argv, char **env) [parser setWordMap: [defs dictionaryForKey: @"WordMap"]]; [parser setVerbose: verbose]; output = [AGSOutput new]; + [output setVerbose: verbose]; if ([defs boolForKey: @"Standards"] == YES) { [parser setGenerateStandards: YES];