Documentation too improvements.

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@13807 72102866-910b-0410-8b05-ffd578937521

ChangeLog

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

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;

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(argList, int*);
-                va_arg(arg_list, char*);
+                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(argList, int*);
-		(void)va_arg(arg_list, char*);
+		(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. */

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

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 = @"<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 = [self checkComment: comment unit: nil info: d];
-    {
-      comment = @"<em>Description forthcoming.</em>";
-    }
   [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 = [self checkComment: comment unit: nil info: d];
-    {
-      comment = @"<em>Description forthcoming.</em>";
-    }
   [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 = [self checkComment: comment unit: unit info: d];
-    {
-      comment = @"<em>Description forthcoming.</em>";
-    }
   [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 = [self checkComment: comment unit: unit info: d];
-    {
-      comment = @"<em>Description forthcoming.</em>";
-    }
   [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"];
+  NSString	*kind = type;
-  NSDictionary	*ivars = [d objectForKey: @"InstanceVariables"];
+  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 = [self checkComment: comment unit: nil info: d];
-    {
-      comment = @"<em>Description forthcoming.</em>";
-    }
   [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];

Tools/AGSParser.m

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

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