gnustep/libs-base
0
0
Fork 0
mirror of https://github.com/gnustep/libs-base.git synced 2025-04-22 16:33:29 +00:00
Code Issues Projects Releases Packages Wiki Activity

Documentation too improvements.

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@13807 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
Richard Frith-Macdonald 2002-06-09 07:31:58 +00:00
parent cc9e39dd04
commit bb79908cca
7 changed files with 111 additions and 57 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
ChangeLog
View file

@ -1,6 +1,8 @@
2002-06-09 Richard Frith-Macdonald <rfm@gnu.org>
* 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 <fedor@gnu.org>

2
Headers/gnustep/base/NSString.h
View file

@ -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;

50
Source/NSString.m
View file

@ -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 = "<null string>";
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 = "<null string>";
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. */

9
Tools/AGSOutput.h
View file

@ -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

100
Tools/AGSOutput.m
View file

@ -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 = @"<em>Description forthcoming.</em>";
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: @" <desc>\n"];
if ([comment length] == 0)
{
comment = @"<em>Description forthcoming.</em>";
}
comment = [self checkComment: comment unit: nil info: d];
[self reformat: comment withIndent: 10 to: str];
[str appendString: @" </desc>\n"];
if (standards != nil)
@ -768,10 +798,7 @@ static BOOL snuggleStart(NSString *t)
}
[str appendString: @" <desc>\n"];
if ([comment length] == 0)
{
comment = @"<em>Description forthcoming.</em>";
}
comment = [self checkComment: comment unit: nil info: d];
[self reformat: comment withIndent: 10 to: str];
[str appendString: @" </desc>\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: @" <desc>\n"];
if ([comment length] == 0)
{
comment = @"<em>Description forthcoming.</em>";
}
comment = [self checkComment: comment unit: unit info: d];
[self reformat: comment withIndent: 12 to: str];
[str appendString: @" </desc>\n"];
if (standards != nil)
@ -981,10 +1007,7 @@ static BOOL snuggleStart(NSString *t)
}
[str appendString: @" <desc>\n"];
if ([comment length] == 0)
{
comment = @"<em>Description forthcoming.</em>";
}
comment = [self checkComment: comment unit: unit info: d];
[self reformat: comment withIndent: 12 to: str];
[str appendString: @" </desc>\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:
@" <chapter>\n <heading>Software documentation "
@"for the %@ %@</heading>\n </chapter>\n", name, type];
@"for the %@ %@</heading>\n </chapter>\n", name, kind];
}
/*
@ -1177,10 +1221,7 @@ static BOOL snuggleStart(NSString *t)
for (j = 0; j < ind; j++) [str appendString: @" "];
[str appendString: @"<desc>\n"];
if ([comment length] == 0)
{
comment = @"<em>Description forthcoming.</em>";
}
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: @"</desc>\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];

4
Tools/AGSParser.m
View file

@ -731,10 +731,6 @@
{
[d setObject: comment forKey: @"Comment"];
}
if (verbose == YES)
{
[self log: @"parse '%@'", d];
}
DESTROY(comment);
}

1
Tools/autogsdoc.m
View file

@ -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];