Documentation and debug logging updates

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

ChangeLog

@@ -1,3 +1,15 @@
+2002-10-08  Richard Frith-Macdonald <rfm@gnu.org>
+
+	* Headers/Foundation/NSDebug.h: Make warn logs de-selectable at
+	runtime by setting the NoWarn debug level.  Document.  Say that
+	debug levels can be added by putting them in the GNU-Debug
+	array in the defaults database.
+	* Source/NSUserDefaults.m: Add contents of the GNU-Debug array to
+	the set of active debug levels.
+	* Tools/AGSParser.m: Updated with support for documenting macros.
+	* Tools/AGSOutput.m: ditto
+	* Tools/AGSHtml.m: ditto
+
 2002-10-07  Richard Frith-Macdonald <rfm@gnu.org>
 
 	* Source/NSData.m: Update logging after checks for results of memory

Headers/gnustep/base/NSDebug.h

@@ -41,35 +41,12 @@ extern int	errno;
  *
  *	Public functions:
  *	GSDebugAllocationActive()	
- *		Activates or deactivates object allocation debugging.
- *		Returns previous state.
- *
  *	GSDebugAllocationCount()	
- *		Returns the number of instances of the specified class
- *		which are currently allocated.
- *
  *      GSDebugAllocationTotal()
- *		Returns the total number of instances of the specified class
- *		which have been allocated.
- *
  *      GSDebugAllocationPeak()
- *		Returns the peak number of instances of the specified class
- *		which have been concurrently allocated.
- *
  *      GSDebugAllocationClassList()
- *              Returns a NULL terminated array listing all the classes 
- *              for which statistical information has been collected.
- *
  *	GSDebugAllocationList()
- *		Returns a newline separated list of the classes which
- *		have instances allocated, and the instance counts.
- *		If 'changeFlag' is YES then the list gives the number
- *		of instances allocated/deallocated since the function
- *		was last called.
  *	GSDebugAllocationListAll()
- *		Returns a newline separated list of the classes which
- *		have had instances allocated at any point, and the total
- *		count of the number of instances allocated for each class.
  *
  * When the previous functions have allowed you to find a memory leak,
  * and you know that you are leaking objects of class XXX, but you are
@@ -80,33 +57,93 @@ extern int	errno;
  * and only in debugging systems):
  *
  *  GSDebugAllocationActiveRecordingObjects()
- *              Starts recording all allocated objects of a certain class
- *
  *  GSDebugAllocationListRecordedObjects() 
- *              Returns an array containing all the allocated objects
+ */
- *              of a certain class which have been recorded.
- *              Presumably, you will immediately call -description on
- *              them to find out the objects you are leaking.
- *              Warning - the objects are put in an array, so until
- *              the array is autoreleased, the objects are not released.  */
-
 #ifndef	NDEBUG
+
+/**
+ * Used internally by NSAllocateObject() ... you probably don't need this.
+ */
 GS_EXPORT void		GSDebugAllocationAdd(Class c, id o);
+
+/**
+ * Used internally by NSDeallocateObject() ... you probably don't need this.
+ */
 GS_EXPORT void		GSDebugAllocationRemove(Class c, id o);
 
+/**
+ * Activates or deactivates object allocation debugging.
+ * Returns previous state.
+ */
 GS_EXPORT BOOL		GSDebugAllocationActive(BOOL active);
+
+/**
+ * Returns the number of instances of the specified class
+ * which are currently allocated.
+ */
 GS_EXPORT int		GSDebugAllocationCount(Class c);
+
+/**
+ * Returns the peak number of instances of the specified class
+ * which have been concurrently allocated.
+ */
 GS_EXPORT int		GSDebugAllocationPeak(Class c);
+
+/**
+ * Returns the total number of instances of the specified class
+ * which have been allocated.
+ */
 GS_EXPORT int		GSDebugAllocationTotal(Class c);
+
+/**
+ * Returns a NULL terminated array listing all the classes 
+ * for which statistical information has been collected.
+ */
 GS_EXPORT Class*        GSDebugAllocationClassList();
+
+/**
+ * Returns a newline separated list of the classes which
+ * have instances allocated, and the instance counts.
+ * If 'changeFlag' is YES then the list gives the number
+ * of instances allocated/deallocated since the function
+ * was last called.
+ */
 GS_EXPORT const char*	GSDebugAllocationList(BOOL changeFlag);
+
+/**
+ * Returns a newline separated list of the classes which
+ * have had instances allocated at any point, and the total
+ * count of the number of instances allocated for each class.
+ */
 GS_EXPORT const char*	GSDebugAllocationListAll();
 
+/**
+ * Starts recording all allocated objects of a certain class.<br />
+ * Use with extreme carre ... this could slow down your application
+ * enormously.
+ */
 GS_EXPORT void     GSDebugAllocationActiveRecordingObjects(Class c);
+
+/**
+ * Returns an array containing all the allocated objects
+ * of a certain class which have been recorded.
+ * Presumably, you will immediately call -description on
+ * them to find out the objects you are leaking.
+ * Warning - the objects are put in an array, so until
+ * the array is autoreleased, the objects are not released.
+ */
 GS_EXPORT NSArray *GSDebugAllocationListRecordedObjects(Class c);
 
+/**
+ * Used to produce a format string for logging a message with function
+ * location details.
+ */
 GS_EXPORT NSString*	GSDebugFunctionMsg(const char *func, const char *file,
 				int line, NSString *fmt);
+/**
+ * Used to produce a format string for logging a message with method
+ * location details.
+ */
 GS_EXPORT NSString*	GSDebugMethodMsg(id obj, SEL sel, const char *file,
 				int line, NSString *fmt);
 #endif
@@ -150,62 +187,104 @@ GS_EXPORT BOOL NSDeallocateZombies;
 
 
 
-/* Debug logging which can be enabled/disabled by defining GSDIAGNOSE
-   when compiling and also setting values in the mutable array
-   that is set up by NSProcessInfo. GSDIAGNOSE is defined autmatically unless
-   diagnose=no is specified in the make arguments.
-
-   NSProcess initialises a set of strings that are the names of active
-   debug levels using the '--GNU-Debug=...' command line argument.
-   Each command-line argument of that form is removed from NSProcessInfos
-   list of arguments and the variable part (...) is added to the set.
-
-   For instance, to debug the NSBundle class, run your program with 
-    '--GNU-Debug=NSBundle'
-   You can of course supply multiple '--GNU-Debug=...' arguments to
-   output debug information on more than one thing.
-
-   To embed debug logging in your code you use the NSDebugLLog() or
-   NSDebugLog() macro.  NSDebugLog() is just NSDebugLLog() with the debug
-   level set to 'dflt'.  So, to activate debug statements that use
-   NSDebugLog(), you supply the '--GNU-Debug=dflt' argument to your program.
-
-   You can also change the active debug levels under your programs control -
-   NSProcessInfo has a [-debugSet] method that returns the mutable set that
-   contains the active debug levels - your program can modify this set.
-
-   As a convenience, there are four more logging macros you can use -
-   NSDebugFLog(), NSDebugFLLog(), NSDebugMLog() and NSDebugMLLog().
-   These are the same as the other macros, but are specifically for use in
-   either functions or methods and prepend information about the file, line
-   and either function or class/method in which the message was generated.
-
- */
 #ifdef GSDIAGNOSE
 #include	<Foundation/NSObjCRuntime.h>
 #include	<Foundation/NSProcessInfo.h>
 
+/**
+   <p>NSDebugLLog() is the basic debug logging macro used to display
+   log messages using NSLog(), if debug logging was enabled at compile
+   time and the appropriate logging level was set at runtime.
+   </p>
+   <p>Debug logging which can be enabled/disabled by defining GSDIAGNOSE
+   when compiling and also setting values in the mutable set which
+   is set up by NSProcessInfo. GSDIAGNOSE is defined automatically
+   unless diagnose=no is specified in the make arguments.
+   </p>
+   <p>NSProcess initialises a set of strings that are the names of active
+   debug levels using the '--GNU-Debug=...' command line argument.
+   Each command-line argument of that form is removed from NSProcessInfos
+   list of arguments and the variable part (...) is added to the set.
+   This means that as far as the program proper is concerned, it is
+   running with the same arguments as if debugging had not been enabled.
+   </p>
+   <p>For instance, to debug the NSBundle class, run your program with 
+    '--GNU-Debug=NSBundle'
+   You can of course supply multiple '--GNU-Debug=...' arguments to
+   output debug information on more than one thing.
+   </p>
+   <p>NSUserDefaults also adds debug levels from the array given by the
+   GNU-Debug key ... but these values will not take effect until the
+   +sharedUserDefaults method is called ... so they are useless for
+   debugging NSUserDefaults itsself or for debugging any code executed
+   before the defaults system is used.
+   </p>
+   <p>To embed debug logging in your code you use the NSDebugLLog() or
+   NSDebugLog() macro.  NSDebugLog() is just NSDebugLLog() with the debug
+   level set to 'dflt'.  So, to activate debug statements that use
+   NSDebugLog(), you supply the '--GNU-Debug=dflt' argument to your program.
+   </p>
+   <p>You can also change the active debug levels under your programs control -
+   NSProcessInfo has a [-debugSet] method that returns the mutable set that
+   contains the active debug levels - your program can modify this set.
+   </p>
+   <p>Two debug levels have a special effect - 'dflt' is the level used for
+   debug logs statements where no debug level is specified, and 'NoWarn'
+   is used to *disable* warning messages.
+   </p>
+   <p>As a convenience, there are four more logging macros you can use -
+   NSDebugFLog(), NSDebugFLLog(), NSDebugMLog() and NSDebugMLLog().
+   These are the same as the other macros, but are specifically for use in
+   either functions or methods and prepend information about the file, line
+   and either function or class/method in which the message was generated.
+   </p>
+ */
 #define NSDebugLLog(level, format, args...) \
   do { if (GSDebugSet(level) == YES) \
     NSLog(format , ## args); } while (0)
+
+/**
+ * This macro is a shorthand for NSDebugLLog() using then default debug
+ * level ... 'dflt'
+ */
 #define NSDebugLog(format, args...) \
   do { if (GSDebugSet(@"dflt") == YES) \
     NSLog(format , ## args); } while (0)
+
+/**
+ * This macro is like NSDebugLLog() but includes the name and location
+ * of the function in which the macro is used as part of the log output.
+ */
 #define NSDebugFLLog(level, format, args...) \
   do { if (GSDebugSet(level) == YES) { \
     NSString *fmt = GSDebugFunctionMsg( \
 	__PRETTY_FUNCTION__, __FILE__, __LINE__, format); \
     NSLog(fmt , ## args); }} while (0)
+
+/**
+ * This macro is a shorthand for NSDebugFLLog() using then default debug
+ * level ... 'dflt'
+ */
 #define NSDebugFLog(format, args...) \
   do { if (GSDebugSet(@"dflt") == YES) { \
     NSString *fmt = GSDebugFunctionMsg( \
 	__PRETTY_FUNCTION__, __FILE__, __LINE__, format); \
     NSLog(fmt , ## args); }} while (0)
+
+/**
+ * This macro is like NSDebugLLog() but includes the name and location
+ * of the <em>method</em> in which the macro is used as part of the log output.
+ */
 #define NSDebugMLLog(level, format, args...) \
   do { if (GSDebugSet(level) == YES) { \
     NSString *fmt = GSDebugMethodMsg( \
 	self, _cmd, __FILE__, __LINE__, format); \
     NSLog(fmt , ## args); }} while (0)
+
+/**
+ * This macro is a shorthand for NSDebugMLLog() using then default debug
+ * level ... 'dflt'
+ */
 #define NSDebugMLog(format, args...) \
   do { if (GSDebugSet(@"dflt") == YES) { \
     NSString *fmt = GSDebugMethodMsg( \
@@ -222,45 +301,65 @@ GS_EXPORT BOOL NSDeallocateZombies;
 
 
 
-/* Warning messages which can be enabled/disabled by defining GSWARN
+#ifdef GSWARN
-   when compiling.
+#include	<Foundation/NSObjCRuntime.h>
 
-   These logging macros are intended to be used when the software detects
+/**
+   <p>NSWarnLog() is the basic debug logging macro used to display
+   warning messages using NSLog(), if warn logging was not disabled at compile
+   time and the disabling logging level was not set at runtime.
+   </p>
+   <p>Warning messages which can be enabled/disabled by defining GSWARN
+   when compiling.
+   </p>
+   <p>You can also disable these messages at runtime by supplying a
+   '--GNU-Debug=NoWarn' argument to the program, or by adding 'NoWarn'
+   to the user default array named 'GNU-Debug'.
+   </p>
+   <p>These logging macros are intended to be used when the software detects
    something that it not necessarily fatal or illegal, but looks like it
    might be a programming error.  eg. attempting to remove 'nil' from an
    NSArray, which the Spec/documentation does not prohibit, but which a
    well written progam should not be attempting (since an NSArray object
    cannot contain a 'nil').
-
+   </p>
-   NB. The 'warn=yes' option is understood by the GNUstep make package
+   <p>NB. The 'warn=yes' option is understood by the GNUstep make package
    to mean that GSWARN should be defined, and the 'warn=no' means that
-    GSWARN should be undefined.  Default is to define it.
+   GSWARN should be undefined.  Default is to define it.
-
+   </p>
-   To embed debug logging in your code you use the NSWarnLog() macro.
+   <p>To embed debug logging in your code you use the NSWarnLog() macro.
-
+   </p>
-   As a convenience, there are two more logging macros you can use -
+   <p>As a convenience, there are two more logging macros you can use -
    NSWarnLog(), and NSWarnMLog().
    These are specifically for use in either functions or methods and
    prepend information about the file, line and either function or
    class/method in which the message was generated.
-
+   </p>
  */
-#ifdef GSWARN
-#include	<Foundation/NSObjCRuntime.h>
 
 #define NSWarnLog(format, args...) \
-  do { \
+  do { if (GSDebugSet(@"NoWarn") == NO) { \
-    NSLog(format , ## args); } while (0)
+    NSLog(format , ## args); }} while (0)
+
+/**
+ * This macro is like NSWarnLog() but includes the name and location of the
+ * <em>function</em> in which the macro is used as part of the log output.
+ */
 #define NSWarnFLog(format, args...) \
-  do { \
+  do { if (GSDebugSet(@"NoWarn") == NO) { \
     NSString *fmt = GSDebugFunctionMsg( \
 	__PRETTY_FUNCTION__, __FILE__, __LINE__, format); \
-    NSLog(fmt , ## args); } while (0)
+    NSLog(fmt , ## args); }} while (0)
+
+/**
+ * This macro is like NSWarnLog() but includes the name and location of the
+ * <em>method</em> in which the macro is used as part of the log output.
+ */
 #define NSWarnMLog(format, args...) \
-  do { \
+  do { if (GSDebugSet(@"NoWarn") == NO) { \
     NSString *fmt = GSDebugMethodMsg( \
 	self, _cmd, __FILE__, __LINE__, format); \
-    NSLog(fmt , ## args); } while (0)
+    NSLog(fmt , ## args); }} while (0)
 #else
 #define NSWarnLog(format, args...)
 #define NSWarnFLog(format, args...)

Source/NSDebug.m

@@ -22,7 +22,7 @@
    License along with this library; if not, write to the Free
    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111 USA.
 
-   <title>NSDebug class reference</title>
+   <title>NSDebug utilities reference</title>
    $Date$ $Revision$
    */
 

Source/NSGeometry.m

@@ -24,14 +24,15 @@
    $Date$ $Revision$
  */ 
 
-/**** Included Headers *******************************************************/
-
 /*
  *	Define IN_NSGEOMETRY_M so that the Foundation/NSGeometry.h header can
  *	provide non-inline versions of the function implementations for us.
  */
 #define	IN_NSGEOMETRY_M
 
+
+/**** Included Headers *******************************************************/
+
 #include <config.h>
 #include <math.h>
 #include <base/preface.h>

Source/NSNotificationQueue.m

@@ -249,6 +249,11 @@ add_to_queue(NSNotificationQueueList *queue, NSNotification *notification,
   NSNotificationQueueRegistration	*item;
 
   item = NSZoneCalloc(_zone, 1, sizeof(NSNotificationQueueRegistration));
+  if (item == 0)
+    {
+      [NSException raise: NSMallocException
+      		  format: @"Unable to add to notification queue"];
+    }
       
   item->notification = RETAIN(notification);
   item->name = [notification name];
@@ -312,12 +317,17 @@ add_to_queue(NSNotificationQueueList *queue, NSNotification *notification,
   _center = RETAIN(notificationCenter);
   _asapQueue = NSZoneCalloc(_zone, 1, sizeof(NSNotificationQueueList));
   _idleQueue = NSZoneCalloc(_zone, 1, sizeof(NSNotificationQueueList));
-
+  if (_asapQueue == 0 || _idleQueue == 0)
-  /*
+    {
-   * insert in global queue list
+      DESTROY(self);
-   */
+    }
-  [NotificationQueueList registerQueue: self];
+  else
-
+    {
+      /*
+       * insert in global queue list
+       */
+      [NotificationQueueList registerQueue: self];
+    }
   return self;
 }
 

Source/NSUserDefaults.m

@@ -46,6 +46,7 @@
 #include <Foundation/NSPathUtilities.h>
 #include <Foundation/NSProcessInfo.h>
 #include <Foundation/NSRunLoop.h>
+#include <Foundation/NSSet.h>
 #include <Foundation/NSThread.h>
 #include <Foundation/NSTimer.h>
 #include <Foundation/NSUtilities.h>
@@ -84,6 +85,26 @@ static void updateCache(NSUserDefaults *self)
 {
   if (self == sharedDefaults)
     {
+      NSArray	*debug;
+
+      /**
+       * If there is an array NSUserDefault called GNU-Debug,
+       * we add its contents to the set of active debug levels.
+       */
+      debug = [self arrayForKey: @"GNU-Debug"];
+      if (debug != nil)
+        {
+	  unsigned	c = [debug count];
+	  NSMutableSet	*s;
+
+	  s = [[NSProcessInfo processInfo] debugSet];
+	  while (c-- > 0)
+	    {
+	      NSString	*level = [debug objectAtIndex: c];
+
+	      [s addObject: level];
+	    }
+	}
       flags[GSMacOSXCompatible]
 	= [self boolForKey: @"GSMacOSXCompatible"];
       flags[GSOldStyleGeometry]

Tools/AGSHtml.m

@@ -1180,6 +1180,118 @@ static NSMutableSet	*textNodes = nil;
 	  [buf appendString:
 	    [self makeAnchor: val ofType: @"label" name: text]];
 	}
+      else if ([name isEqual: @"macro"] == YES)
+	{
+	  NSString	*mac;
+	  NSString	*str;
+	  NSString	*s;
+	  GSXMLNode	*tmp = children;
+	  BOOL		hadArg = NO;
+
+	  mac = [prop objectForKey: @"name"];
+	  str = [NSString stringWithFormat: @" %@", mac];
+	  children = nil;
+	  while (tmp != nil)
+	    {
+	      if ([tmp type] == XML_ELEMENT_NODE)
+		{
+		  if ([[tmp name] isEqual: @"arg"] == YES)
+		    {
+		      GSXMLNode		*t = [tmp firstChild];
+
+		      if (hadArg == YES)
+			{
+			  str = [str stringByAppendingString: @", "];
+			}
+		      else
+		      	{
+			  str = [str stringByAppendingString: @"("];
+			}
+
+		      str = [str stringByAppendingString: @"<b>"];
+		      while (t != nil)
+			{
+			  if ([t type] == XML_TEXT_NODE)
+			    {
+			      NSString	*content = [t content];
+
+			      str = [str stringByAppendingString: content];
+			    }
+			  t = [t next];
+			}
+		      str = [str stringByAppendingString: @"</b>"];
+		      hadArg = YES;
+		    }
+		  else if ([[tmp name] isEqual: @"vararg"] == YES)
+		    {
+		      if (hadArg == YES)
+			{
+			  str = [str stringByAppendingString: @"<b>,...</b>"];
+			}
+		      else
+			{
+			  str = [str stringByAppendingString: @"<b>(...</b>"];
+			}
+		      children = [tmp nextElement];
+		      hadArg = YES;
+		      break;
+		    }
+		  else
+		    {
+		      children = tmp;
+		      break;
+		    }
+		}
+	      tmp = [tmp nextElement];
+	    }
+
+	  /*
+	   * Output macro heading.
+	   */
+	  [buf appendString: indent];
+	  [buf appendString: @"<h3>"];
+	  s = [self makeLink: mac ofType: @"macro" isRef: NO];
+	  if (s != nil)
+	    {
+	      [buf appendString: s];
+	      [buf appendString: mac];
+	      [buf appendString: @"</a>"];
+	    }
+	  else
+	    {
+	      [buf appendString: mac];
+	    }
+	  [buf appendString: @"</h3>\n"];
+	  [buf appendString: indent];
+	  [buf appendString: str];
+	  if (hadArg == YES)
+	    {
+	      [buf appendString: @")"];
+	    }
+	  [buf appendString: @"<br />\n"];
+
+	  node = firstElement(children);
+
+	  if ([[node name] isEqual: @"declared"] == YES)
+	    {
+	      [self outputNode: node to: buf];
+	      node = [node nextElement];
+	    }
+
+	  children = node;
+	  if ([[children name] isEqual: @"standards"])
+	    {
+	      [self outputNode: children to: buf];
+	    }
+
+	  if ([[node name] isEqual: @"desc"])
+	    {
+	      [self outputNode: node to: buf];
+	    }
+
+	  [buf appendString: indent];
+	  [buf appendString: @"<hr width=\"25%\" align=\"left\" />\n"];
+	}
       else if ([name isEqual: @"method"] == YES)
 	{
 	  NSString	*sel;
@@ -1388,8 +1500,7 @@ static NSMutableSet	*textNodes = nil;
 	  unit = nil;
 	}
       else if ([name isEqual: @"EOEntity"] == YES
-	|| [name isEqual: @"EOModel"] == YES
+	|| [name isEqual: @"EOModel"] == YES)
-	|| [name isEqual: @"macro"] == YES)
 	{
 	  NSString	*tmp = [prop objectForKey: @"name"];
 

Tools/AGSOutput.h

@@ -52,6 +52,8 @@
 - (void) outputInstanceVariable: (NSDictionary*)d
 			     to: (NSMutableString*)str
 			    for: (NSString*)unit;
+- (void) outputMacro: (NSDictionary*)d
+		  to: (NSMutableString*)str;
 - (void) outputMethod: (NSDictionary*)d
 		   to: (NSMutableString*)str
 		  for: (NSString*)unit;

Tools/AGSOutput.m

@@ -240,6 +240,7 @@ static BOOL snuggleStart(NSString *t)
   NSDictionary		*types;
   NSDictionary		*variables;
   NSDictionary		*constants;
+  NSDictionary		*macros;
   NSMutableArray	*files;
   NSArray		*authors;
   NSString		*base;
@@ -270,6 +271,7 @@ static BOOL snuggleStart(NSString *t)
   types = [info objectForKey: @"Types"];
   variables = [info objectForKey: @"Variables"];
   constants = [info objectForKey: @"Constants"];
+  macros = [info objectForKey: @"Macros"];
 
   [str appendString: @"<?xml version=\"1.0\"?>\n"];
   [str appendString: @"<!DOCTYPE gsdoc PUBLIC "];
@@ -527,6 +529,42 @@ static BOOL snuggleStart(NSString *t)
       RELEASE(m);
     }
 
+  if ([macros count] > 0)
+    {
+      NSMutableString	*m = [NSMutableString new];
+      NSArray		*names;
+      unsigned		i;
+      unsigned		c = [macros count];
+
+      [m appendString: @"    <chapter>\n"];
+      [m appendFormat: @"      <heading>%@ macros</heading>\n", base];
+      [m appendString: @"      <p></p>\n"];
+
+      names = [macros allKeys];
+      names = [names sortedArrayUsingSelector: @selector(compare:)];
+      for (i = 0; i < c; i++)
+	{
+	  NSString	*name = [names objectAtIndex: i];
+	  NSDictionary	*d = [macros objectForKey: name];
+
+	  [self outputMacro: d to: m];
+	}
+
+      [m appendString: @"    </chapter>\n"];
+
+      tmp = [self mergeMarkup: m ofKind: @"Macros"];
+      if (tmp == nil)
+	{
+	  [str appendString: m];
+	  chapters++;
+	}
+      else
+	{
+	  [files addObject: tmp];
+	}
+      RELEASE(m);
+    }
+
   if ([variables count] > 0)
     {
       NSMutableString	*m = [NSMutableString new];
@@ -796,7 +834,7 @@ static BOOL snuggleStart(NSString *t)
     }
   if ([[d objectForKey: @"VarArgs"] boolValue] == YES)
     {
-      [str appendString: @"<vararg />\n"];
+      [str appendString: @"        <vararg />\n"];
     }
 
   if (declared != nil)
@@ -853,6 +891,64 @@ static BOOL snuggleStart(NSString *t)
   [str appendString: @"        </ivariable>\n"];
 }
 
+/**
+ * Uses -split: and -reformat:withIndent:to:.
+ */
+- (void) outputMacro: (NSDictionary*)d
+		  to: (NSMutableString*)str
+{
+  NSString	*name = [d objectForKey: @"Name"];
+  NSString	*comment = [d objectForKey: @"Comment"];
+  NSString	*declared = [d objectForKey: @"Declared"];
+  NSString	*standards = nil;
+  unsigned	i;
+
+  if (standards == nil)
+    {
+      standards = [d objectForKey: @"Standards"];
+    }
+
+  [str appendString: @"      <macro name=\""];
+  [str appendString: name];
+  [str appendString: @"\">\n"];
+
+  /*
+   * Storing the argument names array in the 'args' ivar ensures that
+   * when we output comments, the argument names are highlighted.
+   */
+  args = [d objectForKey: @"Args"];
+  for (i = 0; i < [args count]; i++)
+    {
+      NSString		*s = [args objectAtIndex: i];
+
+      [str appendString: @"        <arg>"];
+      [str appendString: s];
+      [str appendString: @"</arg>\n"];
+    }
+  if ([[d objectForKey: @"VarArgs"] boolValue] == YES)
+    {
+      [str appendString: @"        <vararg />\n"];
+    }
+
+  if (declared != nil)
+    {
+      [str appendString: @"        <declared>"];
+      [str appendString: declared];
+      [str appendString: @"</declared>\n"];
+    }
+
+  [str appendString: @"        <desc>\n"];
+  comment = [self checkComment: comment unit: nil info: d];
+  [self reformat: comment withIndent: 10 to: str];
+  [str appendString: @"        </desc>\n"];
+  if (standards != nil)
+    {
+      [self reformat: standards withIndent: 8 to: str];
+    }
+  [str appendString: @"      </macro>\n"];
+  args = nil;
+}
+
 /**
  * Uses -split: and -reformat:withIndent:to:.
  * Also has fun with YES, NO, and nil.
@@ -1013,7 +1109,7 @@ static BOOL snuggleStart(NSString *t)
     }
   if ([[d objectForKey: @"VarArgs"] boolValue] == YES)
     {
-      [str appendString: @"<vararg />\n"];
+      [str appendString: @"          <vararg />\n"];
     }
 
   [str appendString: @"          <desc>\n"];

Tools/AGSParser.h

@@ -54,6 +54,7 @@
   unichar	*buffer;
   unsigned	length;
   unsigned	pos;
+  BOOL		inHeader;
   BOOL		commentsRead;
   BOOL		haveOutput;
   BOOL		haveSource;
@@ -62,6 +63,7 @@
   BOOL		documentAllInstanceVariables;
   BOOL		verbose;
   BOOL		warn;
+  BOOL		standards;
   NSDictionary		*wordMap;
   NSString		*declared;	/** Where classes were declared. */
   NSMutableArray	*ifStack;	/** Track preprocessor conditionals. */
@@ -78,17 +80,22 @@
 - (NSMutableDictionary*) info;
 - (id) init;	/** <init> Simple initialiser */
 - (NSMutableArray*) outputs;
+- (unsigned) parseComment;
 - (NSMutableDictionary*) parseDeclaration;
 - (NSMutableDictionary*) parseFile: (NSString*)name isSource: (BOOL)isSource;
 - (NSString*) parseIdentifier;
 - (NSMutableDictionary*) parseImplementation;
 - (NSMutableDictionary*) parseInterface;
 - (NSMutableDictionary*) parseInstanceVariables;
+- (NSMutableDictionary*) parseMacro;
 - (NSMutableDictionary*) parseMethodIsDeclaration: (BOOL)flag;
 - (NSMutableDictionary*) parseMethodsAreDeclarations: (BOOL)flag;
 - (NSString*) parseMethodType;
+- (unsigned) parsePreprocessor;
 - (NSMutableDictionary*) parseProtocol;
 - (NSMutableArray*) parseProtocolList;
+- (unsigned) parseSpace: (NSCharacterSet*)spaces;
+- (unsigned) parseSpace;
 - (void) reset;
 - (void) setDeclared: (NSString*)name;
 - (void) setDocumentAllInstanceVariables: (BOOL)flag;
@@ -98,15 +105,18 @@
 - (void) setupBuffer;
 - (unsigned) skipArray;
 - (unsigned) skipBlock;
-- (unsigned) skipComment;
 - (unsigned) skipLiteral;
-- (unsigned) skipPreprocessor;
 - (unsigned) skipRemainderOfLine;
 - (unsigned) skipSpaces;
 - (unsigned) skipStatement;
 - (unsigned) skipStatementLine;
+- (unsigned) skipToEndOfLine;
 - (unsigned) skipUnit;
-- (unsigned) skipWhiteSpace;
 - (NSMutableArray*) sources;
 @end
+
+/** Let's document a macro
+ */
+#define	fibble(a,b,c)	feep /** with three arguments: a, b, c */
+
 #endif