Documentation improvements

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

ChangeLog

@@ -1,3 +1,11 @@
+2002-01-01  Richard Frith-Macdonald <rfm@gnu.org>
+
+	* Source/GNUmakefile: Use new -Standards flag for autogsdoc
+	* Tools/AGSparser.[hm]: New support for standards and some tidyups
+	* Tools/AGSHtml.[hm]: Improved output and simplified a little.
+	* Tools/autogsdoc.m: New Standards flag to turn on support for
+	generation of standards complience notes in documentation.
+
 Tue Jan  1 11:18:35 2002  Nicola Pero  <n.pero@mi.flashnet.it>
 
 	* Source/NSFileManager.m (custom_strdup): New inline function

Headers/gnustep/base/NSUserDefaults.h

@@ -136,8 +136,12 @@ GS_EXPORT NSString* const NSLocale;
  */
 + (void) resetStandardUserDefaults;
 #endif
+#ifndef	STRICT_OPENSTEP
+#ifndef	STRICT_MACOS_X
 + (NSArray*) userLanguages;
 + (void) setUserLanguages: (NSArray*)languages;
+#endif
+#endif
 
 /* Initializing the User Defaults */
 - (id) init;

Source/GNUmakefile

@@ -429,7 +429,10 @@ libgnustep-base_HEADER_FILES = $(FOUNDATION_HEADERS)
 DOCUMENT_NAME = Base
 
 Base_AGSDOC_FILES = $(FOUNDATION_HEADERS)
-Base_AGSDOC_FLAGS = -HeaderDirectory ../Headers/Foundation -Declared Foundation
+Base_AGSDOC_FLAGS = \
+	-HeaderDirectory ../Headers/Foundation \
+	-Declared Foundation \
+	-Standards YES
 
 -include Makefile.preamble
 

Tools/AGSHtml.m

@@ -488,6 +488,27 @@ static NSMutableSet	*textNodes = nil;
 	      [buf appendString: @"<hr width=\"50%\" align=\"left\" />\n"];
 	    }
 	}
+      else if ([name isEqual: @"declared"] == YES)
+	{
+	  [buf appendString: indent];
+	  [buf appendString: @"<blockquote>\n"];
+	  [self incIndent];
+	  [buf appendString: indent];
+	  [buf appendString: @"<dl>\n"];
+	  [self incIndent];
+	  [buf appendString: indent];
+	  [buf appendString: @"<dt><b>Declared in:</b></dt>\n"];
+	  [buf appendString: indent];
+	  [buf appendString: @"<dd>"];
+	  [self outputText: [node children] to: buf];
+	  [buf appendString: @"</dd>\n"];
+	  [self decIndent];
+	  [buf appendString: indent];
+	  [buf appendString: @"</dl>\n"];
+	  [self decIndent];
+	  [buf appendString: indent];
+	  [buf appendString: @"</blockquote>\n"];
+	}
       else if ([name isEqual: @"desc"] == YES)
 	{
 	  [buf appendString: indent];
@@ -985,19 +1006,7 @@ static NSMutableSet	*textNodes = nil;
 	      children = [node next];
 	      if ([[children name] isEqual: @"standards"])
 		{
-		  tmp = [children children];
-		  if (tmp != nil)
-		    {
-		      [buf appendString: indent];
-		      [buf appendString: @"<b>Standards:</b>"];
-		      while (tmp != nil)
-			{
-			  [buf appendString: @" "];
-			  [buf appendString: [tmp name]];
-			  tmp = [tmp next];
-			}
-		      [buf appendString: @"<br />\n"];
-		    }
+		  [self outputNode: children to: buf];
 		}
 
 	      if ((str = [prop objectForKey: @"init"]) != nil
@@ -1100,6 +1109,32 @@ static NSMutableSet	*textNodes = nil;
 	  [self outputText: children to: buf];
 	  [buf appendString: @"</code>"];
 	}
+      else if ([name isEqual: @"standards"])
+	{
+	  GSXMLNode	*tmp = [node children];
+	  BOOL		first = YES;
+
+	  if (tmp != nil)
+	    {
+	      [buf appendString: indent];
+	      [buf appendString: @"<b>Standards:</b>"];
+	      while (tmp != nil)
+		{
+		  if (first == YES)
+		    {
+		      first = NO;
+		      [buf appendString: @" "];
+		    }
+		  else
+		    {
+		      [buf appendString: @", "];
+		    }
+		  [buf appendString: [tmp name]];
+		  tmp = [tmp next];
+		}
+	      [buf appendString: @"<br />\n"];
+	    }
+	}
       else if ([name isEqual: @"strong"] == YES)
 	{
 	  [buf appendString: @"<strong>"];
@@ -1135,10 +1170,7 @@ static NSMutableSet	*textNodes = nil;
 
 	  if (node != nil && [[node name] isEqual: @"declared"] == YES)
 	    {
-	      [buf appendString: indent];
-	      [buf appendString: @"Declared: "];
-	      [self outputText: [node children] to: buf];
-	      [buf appendString: @"<br />\n"];
+	      [self outputNode: node to: buf];
 	      node = [node next];
 	    }
 	  if (node != nil && [[node name] isEqual: @"desc"] == YES)
@@ -1450,29 +1482,13 @@ NSLog(@"Element '%@' not implemented", name); // FIXME
 
 - (void) outputUnit: (GSXMLNode*)node to: (NSMutableString*)buf
 {
+  GSXMLNode		*t;
   NSMutableArray	*a;
 
   node = [node children];
   if (node != nil && [[node name] isEqual: @"declared"] == YES)
     {
-      [buf appendString: indent];
-      [buf appendString: @"<blockquote>\n"];
-      [self incIndent];
-      [buf appendString: indent];
-      [buf appendString: @"<dl>\n"];
-      [self incIndent];
-      [buf appendString: indent];
-      [buf appendString: @"<dt><b>Declared in:</b></dt>\n"];
-      [buf appendString: indent];
-      [buf appendString: @"<dd>"];
-      [self outputText: [node children] to: buf];
-      [buf appendString: @"</dd>\n"];
-      [self decIndent];
-      [buf appendString: indent];
-      [buf appendString: @"</dl>\n"];
-      [self decIndent];
-      [buf appendString: indent];
-      [buf appendString: @"</blockquote>\n"];
+      [self outputNode: node to: buf];
       node = [node next];
     }
 
@@ -1510,6 +1526,38 @@ NSLog(@"Element '%@' not implemented", name); // FIXME
       node = [node next];
     }
 
+  t = node;
+  while (t != nil && [[t name] isEqual: @"standards"] == NO)
+    {
+      t = [t next];
+    }
+  if (t != nil && [t children] != nil)
+    {
+      t = [t children];
+      [buf appendString: indent];
+      [buf appendString: @"<blockquote>\n"];
+      [self incIndent];
+      [buf appendString: indent];
+      [buf appendString: @"<b>Standards:</b>\n"];
+      [buf appendString: indent];
+      [buf appendString: @"<ul>\n"];
+      [self incIndent];
+      while (t != nil)
+	{
+	  [buf appendString: indent];
+	  [buf appendString: @"<li>"];
+	  [buf appendString: [t name]];
+	  [buf appendString: @"</li>\n"];
+	  t = [t next];
+	}
+      [self decIndent];
+      [buf appendString: indent];
+      [buf appendString: @"</ul>\n"];
+      [self decIndent];
+      [buf appendString: indent];
+      [buf appendString: @"</blockquote>\n"];
+    }
+
   a = [localRefs methodsInUnit: unit];
   if ([a count] > 0)
     {
@@ -1545,24 +1593,6 @@ NSLog(@"Element '%@' not implemented", name); // FIXME
       [self outputNode: node to: buf];
       node = [node next];
     }
-  if (node != nil && [[node name] isEqual: @"standards"] == YES)
-    {
-      GSXMLNode	*tmp = [node children];
-
-      if (tmp != nil)
-	{
-	  [buf appendString: indent];
-	  [buf appendString: @"<b>Standards:</b>"];
-	  while (tmp != nil)
-	    {
-	      [buf appendString: @" "];
-	      [buf appendString: [tmp name]];
-	      tmp = [tmp next];
-	    }
-	  [buf appendString: @"<br />\n"];
-	}
-      node = [node next];
-    }
 }
 
 /**

Tools/AGSParser.h

@@ -81,6 +81,8 @@
 - (NSMutableArray*) parseProtocolList;
 - (void) reset;
 - (void) setDeclared: (NSString*)name;
+- (void) setGenerateStandards: (BOOL)flag;
+- (void) setStandards: (NSMutableDictionary*)dict;
 - (void) setupBuffer;
 - (unsigned) skipBlock;
 - (unsigned) skipComment;
@@ -92,6 +94,5 @@
 - (unsigned) skipStatementLine;
 - (unsigned) skipUnit;
 - (unsigned) skipWhiteSpace;
-- (void) setStandards: (NSMutableDictionary*)dict;
 @end
 #endif

Tools/AGSParser.m

@@ -57,7 +57,6 @@
   identStart = RETAIN([NSCharacterSet characterSetWithCharactersInString:
     @"_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"]);
   info = [[NSMutableDictionary alloc] initWithCapacity: 6];
-  ifStack = [[NSMutableArray alloc] initWithCapacity: 4];
   return self;
 }
 
@@ -1206,6 +1205,96 @@ fail:
   ASSIGN(declared, name);
 }
 
+/**
+ * Turn on or off parsing of preprocessor conditional compilation info
+ * indicating the standards complied with.  When this is turned on, we
+ * assume that all standards are complied with by default.<br />
+ * You should only turn this on while parsing the GNUstep source code.
+ */
+- (void) setGenerateStandards: (BOOL)flag
+{
+  if (flag == NO)
+    {
+      DESTROY(ifStack);
+    }
+  else if (ifStack == nil)
+    {
+      ifStack = [[NSMutableArray alloc] initWithCapacity: 4];
+      [ifStack addObject: @"OpenStep"];
+      [ifStack addObject: @"MacOS-X"];
+      [ifStack addObject: @"GNUstep"];
+    }
+}
+
+/**
+ * Store the current standards information derived from preprocessor
+ * conditionals in the supplied dictionary ... this will be used by
+ * the AGSOutput class to put standards markup in the gsdoc output.
+ */
+- (void) setStandards: (NSMutableDictionary*)dict
+{
+  unsigned		c = [ifStack count];
+  BOOL			hadG = NO;
+  BOOL			hadM = NO;
+  BOOL			hadO = NO;
+
+  if (c > 0)
+    {
+      NSMutableString	*s = nil;
+      BOOL		found = NO;
+
+      s = [NSMutableString stringWithCString: "<standards>"];
+      while (c-- > 0)
+	{
+	  NSString	*name = [ifStack objectAtIndex: c];
+
+	  /*
+	   * We don't produce output for empty strings or
+	   * the 'NotGNUstep' string.
+	   */
+	  if ([name isEqualToString: @""] == YES
+	    || [name isEqualToString: @"NotGNUstep"] == YES)
+	    {
+	      continue;
+	    }
+	  if ([name isEqualToString: @"GNUstep"] == YES
+	    || [name isEqualToString: @"NotGNUstep"] == YES)
+	    {
+	      if (hadG == YES)
+		{
+		  continue;
+		}
+	      hadG = YES;
+	    }
+	  if ([name isEqualToString: @"OpenStep"] == YES
+	    || [name isEqualToString: @"NotOpenStep"] == YES)
+	    {
+	      if (hadO == YES)
+		{
+		  continue;
+		}
+	      hadO = YES;
+	    }
+	  if ([name isEqualToString: @"MacOS-X"] == YES
+	    || [name isEqualToString: @"NotMacOS-X"] == YES)
+	    {
+	      if (hadM == YES)
+		{
+		  continue;
+		}
+	      hadM = YES;
+	    }
+	  found = YES;
+	  [s appendFormat: @"<%@ />", name];
+	}
+      if (found == YES)
+	{
+	  [s appendString: @"</standards>"];
+	  [dict setObject: s forKey: @"Standards"];
+	}
+    }
+}
+
 /**
  * Read in the file to be parsed and store it in a temporary unicode
  * buffer.  Perform basic transformations on the buffer to simplify
@@ -1821,6 +1910,14 @@ fail:
  */
 - (unsigned) skipPreprocessor
 {
+  /*
+   * If we are not doing preprocessor handling ... just skip to end of line.
+   */
+  if (ifStack == nil)
+    {
+      return [self skipRemainderOfLine];
+    }
+
   while (pos < length && [spaces characterIsMember: buffer[pos]] == YES)
     {
       pos++;
@@ -2107,42 +2204,5 @@ fail:
   return pos;
 }
 
-/**
- * Store the current standards information derived from preprocessor
- * conditionals in the supplied dictionary ... this will be used by
- * the AGSOutput class to put standards markup in the gsdoc output.
- */
-- (void) setStandards: (NSMutableDictionary*)dict
-{
-  unsigned		c = [ifStack count];
-
-  if (c > 0)
-    {
-      NSMutableString	*s = nil;
-      BOOL		found = NO;
-
-      s = [NSMutableString stringWithCString: "<standards>"];
-      while (c-- > 0)
-	{
-	  NSString	*name = [ifStack objectAtIndex: c];
-
-	  /*
-	   * We don't produce output for empty strings or
-	   * the 'NotGNUstep' string.
-	   */
-	  if ([name isEqualToString: @""] == NO
-	    && [name isEqualToString: @"NotGNUstep"] == NO)
-	    {
-	      found = YES;
-	      [s appendFormat: @"<%@ />", name];
-	    }
-	}
-      if (found == YES)
-	{
-	  [s appendString: @"</standards>"];
-	  [dict setObject: s forKey: @"Standards"];
-	}
-    }
-}
 @end
 

Tools/autogsdoc.m

@@ -252,6 +252,14 @@
       log which files are being regenerated because of their dependencies
       on other files.
     </item>
+    <item><strong>Standards</strong>
+      A boolean value used to specify whether the program should insert
+      information about standards complience into ythe documentation.
+      This should only be used when documenting the GNUstep libraries
+      and tools themselves as it assumes that the code being documented
+      is part of GNUstep and possibly complies with the OpenStep standard
+      or implements MacOS-X compatible methods.
+    </item>
     <item><strong>SourceDirectory</strong>
       May be used to specify the directory to be searched for source
       (anything other than <code>.h</code> files ... which are controlled
@@ -342,6 +350,7 @@ main(int argc, char **argv, char **env)
   BOOL			showDependencies = NO;
   BOOL			autoIndex = NO;
   BOOL			modifiedRefs = NO;
+  BOOL			standards = NO;
   NSDate		*rDate = nil;
   NSMutableArray	*files = nil;
   CREATE_AUTORELEASE_POOL(outer);
@@ -359,6 +368,7 @@ main(int argc, char **argv, char **env)
     nil]];
 
   autoIndex = [defs boolForKey: @"AutoIndex"];
+  standards = [defs boolForKey: @"Standards"];
   ignoreDependencies = [defs boolForKey: @"IgnoreDependencies"];
   showDependencies = [defs boolForKey: @"ShowDependencies"];
   if (ignoreDependencies == YES)
@@ -464,6 +474,7 @@ main(int argc, char **argv, char **env)
   prjRefs = [AGSIndex new];
   indexer = [AGSIndex new];
   parser = [AGSParser new];
+  [parser setGenerateStandards: standards];
   output = [AGSOutput new];
 
   /*