Improve documentation generation

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

ChangeLog

@@ -1,3 +1,19 @@
+2002-02-03  Richard Frith-Macdonald <rfm@gnu.org>
+
+	* Source/GNUmakefile: use -WordMap flag with autogsdoc to cope with
+	C-preprocessor constants that would otherwise confuse parsing.
+	* Source/NSDictionary.m: Tidy to match interface.
+	* Source/NSDistantObject.m: Tidy to match interface.
+	* Source/NSPortCoder.m: Tidy to match interface.
+	* Source/NSScanner.m: Tidy to match interface.  Remove some illegal
+	semicolons after method names.
+	* Source/NSTimer.m: Tidy to match interface.
+	* Tools/AGSParser.h: Handle word mappings.
+	* Tools/AGSParser.m: Handle word mappings and deal with function
+	attributes.
+	* Tools/autogsdoc.m: Handle word mappings and make default logging
+	less verbose.
+
 2002-02-02  Richard Frith-Macdonald <rfm@gnu.org>
 
 	* Source/NSObject.m: Fix some maptable problems when using non-local

Source/GNUmakefile

@@ -381,7 +381,13 @@ Base_AGSDOC_FLAGS = \
 	-HeaderDirectory ../Headers/Foundation \
 	-Declared Foundation \
 	-Standards YES \
-	-Up Base
+	-WordMap '{\
+	FOUNDATION_EXPORT=extern;FOUNDATION_STATIC_INLINE="";\
+	GS_GEOM_SCOPE=extern;GS_GEOM_ATTR="";\
+	GS_EXPORT=extern;GS_DECLARE="";\
+	GS_RANGE_SCOPE=extern;GS_RANGE_ATTR="";\
+	GS_ZONE_SCOPE=extern;GS_ZONE_ATTR="";\
+	}' -Up Base
 
 -include Makefile.preamble
 

Source/NSDictionary.m

@@ -354,12 +354,18 @@ static SEL	appSel;
   return [self initWithObjects: NULL forKeys: NULL count: 0];
 }
 
-- (id) initWithDictionary: (NSDictionary*)other
+- (id) initWithDictionary: (NSDictionary*)otherDictionary
 {
-  return [self initWithDictionary: other copyItems: NO];
+  return [self initWithDictionary: otherDictionary copyItems: NO];
 }
 
-- (id) initWithDictionary: (NSDictionary*)other copyItems: (BOOL)shouldCopy
+/**
+ * Initialise dictionary with the keys and values of otherDictionary.
+ * If the shouldCopy flag is YES then the values are copied into the
+ * newly initialised dictionary, otherwise they are simply retained.
+ */
+- (id) initWithDictionary: (NSDictionary*)other
+		copyItems: (BOOL)shouldCopy
 {
   unsigned	c = [other count];
 
@@ -1062,19 +1068,24 @@ static NSString	*indentStrings[] = {
     }
 }
 
-- (void) addEntriesFromDictionary: (NSDictionary*)other
+/**
+ * Merges information from otherDictionary into the receiver.
+ * If a key exists in both dictionaries, the value from otherDictionary
+ * replaces that which was originally in the reciever.
+ */
+- (void) addEntriesFromDictionary: (NSDictionary*)otherDictionary
 {
-  if (other != nil && other != self)
+  if (otherDictionary != nil && otherDictionary != self)
     {
       id		k;
-      NSEnumerator	*e = [other keyEnumerator];
+      NSEnumerator	*e = [otherDictionary keyEnumerator];
       IMP		nxtObj = [e methodForSelector: nxtSel];
-      IMP		getObj = [other methodForSelector: objSel];
+      IMP		getObj = [otherDictionary methodForSelector: objSel];
       IMP		setObj = [self methodForSelector: setSel];
 
       while ((k = (*nxtObj)(e, nxtSel)) != nil)
 	{
-	  (*setObj)(self, setSel, (*getObj)(other, objSel, k), k);
+	  (*setObj)(self, setSel, (*getObj)(otherDictionary, objSel, k), k);
 	}
     }
 }

Source/NSDistantObject.m

@@ -68,7 +68,7 @@ enum
   PROXY_LOCAL_FOR_RECEIVER = 0,
   PROXY_LOCAL_FOR_SENDER,
   PROXY_REMOTE_FOR_BOTH
-};
+} proxyLocation;
 
 
 

Source/NSPortCoder.m

@@ -329,7 +329,7 @@ static IMP	_xRefImp;	/* Serialize a crossref.	*/
 
 + (NSPortCoder*) portCoderWithReceivePort: (NSPort*)recv
 				 sendPort: (NSPort*)send
-			       components: (NSArray*)comp;
+			       components: (NSArray*)comp
 {
   id	coder;
 
@@ -1266,11 +1266,11 @@ static IMP	_xRefImp;	/* Serialize a crossref.	*/
  * array, and simply record the array index, so the corresponding decode
  * method can tell which component to use.
  */
-- (void) encodePortObject: (NSPort*)anObject
+- (void) encodePortObject: (NSPort*)aPort
 {
   unsigned	pos = [_comp count];
 
-  [_comp addObject: anObject];
+  [_comp addObject: aPort];
   [self encodeValueOfObjCType: @encode(unsigned) at: &pos];
 }
 

Source/NSScanner.m

@@ -708,7 +708,7 @@ typedef struct {
  * containing the scanned characters is returned by reference in value.
  */
 - (BOOL) scanCharactersFromSet: (NSCharacterSet *)aSet 
-		    intoString: (NSString **)value;
+		    intoString: (NSString **)value
 {
   unsigned int	saveScanLocation = _scanLocation;
 
@@ -766,8 +766,8 @@ typedef struct {
  * If value is non-NULL, and any characters were scanned, a string
  * containing the scanned characters is returned by reference in value.
  */
-- (BOOL) scanUpToCharactersFromSet: (NSCharacterSet *)set 
+- (BOOL) scanUpToCharactersFromSet: (NSCharacterSet *)aSet 
-		        intoString: (NSString **)value;
+		        intoString: (NSString **)value
 {
   unsigned int	saveScanLocation = _scanLocation;
   unsigned int	start;
@@ -776,18 +776,18 @@ typedef struct {
   if (!skipToNextField())
     return NO;
 
-  if (set == _charactersToBeSkipped)
+  if (aSet == _charactersToBeSkipped)
     memImp = _skipImp;
   else
     memImp = (BOOL (*)(NSCharacterSet*, SEL, unichar))
-      [set methodForSelector: memSel];
+      [aSet methodForSelector: memSel];
 
   start = _scanLocation;
   if (_isUnicode)
     {
       while (_scanLocation < myLength())
 	{
-	  if ((*memImp)(set, memSel, myUnicode(_scanLocation)) == YES)
+	  if ((*memImp)(aSet, memSel, myUnicode(_scanLocation)) == YES)
 	    break;
 	  _scanLocation++;
 	}
@@ -796,7 +796,7 @@ typedef struct {
     {
       while (_scanLocation < myLength())
 	{
-	  if ((*memImp)(set, memSel, myChar(_scanLocation)) == YES)
+	  if ((*memImp)(aSet, memSel, myChar(_scanLocation)) == YES)
 	    break;
 	  _scanLocation++;
 	}
@@ -826,17 +826,17 @@ typedef struct {
  * If value is non-NULL, and the characters at the scan location match aString,
  * a string containing the matching string is returned by reference in value.
  */
-- (BOOL) scanString: (NSString *)aString intoString: (NSString **)value;
+- (BOOL) scanString: (NSString *)string intoString: (NSString **)value
 {
   NSRange	range;
   unsigned int	saveScanLocation = _scanLocation;
     
   skipToNextField();
   range.location = _scanLocation;
-  range.length = [aString length];
+  range.length = [string length];
   if (range.location + range.length > myLength())
     return NO;
-  range = [_string rangeOfString: aString
+  range = [_string rangeOfString: string
 			options: _caseSensitive ? 0 : NSCaseInsensitiveSearch
 			  range: range];
   if (range.length == 0)
@@ -857,8 +857,8 @@ typedef struct {
  * If value is non-NULL, and any characters were scanned, a string
  * containing the scanned characters is returned by reference in value.
  */
-- (BOOL) scanUpToString: (NSString *)aString 
+- (BOOL) scanUpToString: (NSString *)string 
-	     intoString: (NSString **)value;
+	     intoString: (NSString **)value
 {
   NSRange	range;
   NSRange	found;
@@ -867,7 +867,7 @@ typedef struct {
   skipToNextField();
   range.location = _scanLocation;
   range.length = myLength() - _scanLocation;
-  found = [_string rangeOfString: aString
+  found = [_string rangeOfString: string
 			 options: _caseSensitive ? 0 : NSCaseInsensitiveSearch
 			   range: range];
   if (found.length)

Source/NSTimer.m

@@ -46,25 +46,25 @@ static Class	NSDate_class;
     }
 }
 
-/*
+/**
  * <init />
  * Initialise a newly allocated NSTimer object.
  */
-- (id) initWithTimeInterval: (NSTimeInterval)seconds
+- (id) initWithTimeInterval: (NSTimeInterval)ti
-	 targetOrInvocation: (id)t
+	 targetOrInvocation: (id)object
-		   selector: (SEL)sel
+		   selector: (SEL)selector
-		   userInfo: info
+		   userInfo: (id)info
 		    repeats: (BOOL)f
 {
-  if (seconds <= 0)
+  if (ti <= 0)
     {
-      seconds = 0.0001;
+      ti = 0.0001;
     }
-  _interval = seconds;
+  _interval = ti;
   _date = [[NSDate_class allocWithZone: [self zone]]
-    initWithTimeIntervalSinceNow: seconds];
+    initWithTimeIntervalSinceNow: ti];
-  _target = t;
+  _target = object;
-  _selector = sel;
+  _selector = selector;
   _info = info;
   _repeats = f;
   return self;

Tools/AGSParser.h

@@ -59,6 +59,8 @@
   BOOL		inInstanceVariables;
   BOOL		inArgList;
   BOOL		documentAllInstanceVariables;
+  BOOL		verbose;
+  NSDictionary		*wordMap;
   NSString		*declared;	/** Where classes were declared. */
   NSMutableArray	*ifStack;	/** Track preprocessor conditionals. */
 
@@ -89,6 +91,8 @@
 - (void) setDocumentAllInstanceVariables: (BOOL)flag;
 - (void) setGenerateStandards: (BOOL)flag;
 - (void) setStandards: (NSMutableDictionary*)dict;
+- (void) setVerbose: (BOOL)flag;
+- (void) setWordMap: (NSDictionary*)map;
 - (void) setupBuffer;
 - (unsigned) skipArray;
 - (unsigned) skipBlock;

Tools/AGSParser.m

@@ -26,6 +26,7 @@
 
 - (void) dealloc
 {
+  DESTROY(wordMap);
   DESTROY(ifStack);
   DESTROY(declared);
   DESTROY(info);
@@ -272,6 +273,7 @@
   NSString		*s;
   BOOL			isTypedef = NO;
   BOOL			isPointer = NO;
+  BOOL			isFunction = NO;
   BOOL			baseConstant = NO;
   BOOL			needScalarType = NO;
 
@@ -574,6 +576,7 @@
       if (isPointer == NO || [d objectForKey: @"Suffix"] == nil)
 	{
 	  [d setObject: @"function" forKey: @"Kind"];
+	  isFunction = YES;
 	}
     }
 
@@ -595,6 +598,27 @@
 	}
       else
 	{
+	  if (isFunction == YES)
+	    {
+	      NSString	*ident = [self parseIdentifier];
+
+	      if ([ident isEqual: @"__attribute__"] == YES)
+		{
+		  if ([self skipSpaces] < length && buffer[pos] == '(')
+		    {
+		      [self skipBlock];	// Skip the attributes
+		    }
+		  else
+		    {
+		      [self log: @"strange format function attributes"];
+		    }
+		}
+	      else if (ident != nil)
+		{
+		  [self log: @"ignoring '%@' in function declaration", ident];
+		}
+	    }
+
 	  if (buffer[pos] == ';')
 	    {
 	      [self skipStatement];
@@ -631,7 +655,10 @@
 	    {
 	      [d setObject: comment forKey: @"Comment"];
 	    }
-	  [self log: @"parse '%@'", d];
+	  if (verbose == YES)
+	    {
+	      [self log: @"parse '%@'", d];
+	    }
 	  DESTROY(comment);
 	}
 
@@ -1021,10 +1048,19 @@ fail:
   return nil;
 }
 
+/**
+ * Attempt to parse an identifier/keyword (with optional whitespace in
+ * front of it).  Perform mappings using the wordMap dictionary.  If a
+ * mapping produces an empty string, we treat it as if we had read
+ * whitespace and try again.
+ * If we read end of data, or anything which is invalid inside an
+ * identifier, we return nil.
+ */
 - (NSString*) parseIdentifier
 {
   unsigned	start;
 
+try:
   [self skipWhiteSpace];
   if (pos >= length || [identStart characterIsMember: buffer[pos]] == NO)
     {
@@ -1035,8 +1071,21 @@ fail:
     {
       if ([identifier characterIsMember: buffer[pos]] == NO)
 	{
-	  return [NSString stringWithCharacters: &buffer[start]
+	  NSString	*tmp;
-					 length: pos - start];
+	  NSString	*val;
+
+	  tmp = [NSString stringWithCharacters: &buffer[start]
+					length: pos - start];
+	  val = [wordMap objectForKey: tmp];
+	  if (val == nil)
+	    {
+	      return tmp;	// No mapping found.
+	    }
+	  else if ([val length] > 0)
+	    {
+	      return val;	// Got mapped identifier.
+	    }
+	  goto try;		// Mapping removed the identifier.
 	}
       pos++;
     }
@@ -1849,6 +1898,24 @@ fail:
     }
 }
 
+/**
+ * Control boolean option to do verbose logging of the parsing process.
+ */
+- (void) setVerbose: (BOOL)flag
+{
+  verbose = flag;
+}
+
+/**
+ * Sets up a dictionary used for mapping identifiers/keywords to other
+ * words.  This is used to help cope with cases where C preprocessor
+ * definitions are confusing the parsing process.
+ */
+- (void) setWordMap: (NSDictionary*)map
+{
+  ASSIGNCOPY(wordMap, map);
+}
+
 /**
  * Read in the file to be parsed and store it in a temporary unicode
  * buffer.  Perform basic transformations on the buffer to simplify
@@ -2001,12 +2068,22 @@ fail:
 }
 
 /**
- * Skip until we encounter an '}' marking the end of a block.
+ * Skip a bracketed block.
  * Expect the current character position to be pointing to the
- * '{' at the start of a block.
+ * bracket at the start of a block.
  */
 - (unsigned) skipBlock
 {
+  unichar	term = '}';
+
+  if (buffer[pos] == '(')
+    {
+      term = ')';
+    }
+  else if (buffer[pos] == '[')
+    {
+      term = ']';
+    }
   pos++;
   while ([self skipWhiteSpace] < length)
     {
@@ -2029,8 +2106,21 @@ fail:
 	    [self skipBlock];
 	    break;
 
-	  case '}':
+	  case '(':
-	    return pos;
+	    pos--;
+	    [self skipBlock];
+	    break;
+
+	  case '[':
+	    pos--;
+	    [self skipBlock];
+	    break;
+
+	  default:
+	    if (c == term)
+	      {
+		return pos;
+	      }
         }
     }
   return pos;

Tools/autogsdoc.m

@@ -246,7 +246,7 @@
       items in this project.
     </item>
     <item><strong>Projects</strong>
-      This value may be supplies as a dictionary containing the paths to
+      This value may be supplied as a dictionary containing the paths to
       the igsdoc index/reference files used by external projects, along
       with values to be used to map the filenames found in the indexes.<br />
       For example, if a project index (igsdoc) file says that the class
@@ -289,6 +289,13 @@
       If this is missing or set to an empty string, then no 'up' link
       will be provided in the documents.
     </item>
+    <item><strong>WordMap</strong>
+      This value is a dictionary used to map identifiers/keywords found
+      in the source files  to other words.  Generally you will not have
+      to use this, but it is sometimes helpful to avoid the parser being
+      confused by the use of C preprocessor macros.  You can effectively
+      redefine the macro to something less confusing.
+    </item>
   </list>
   <section>
     <heading>Inter-document linkage</heading>
@@ -430,9 +437,12 @@ main(int argc, char **argv, char **env)
   gFiles = [NSMutableArray array];
   hFiles = [NSMutableArray array];
   count = [files count];
-NSLog(@"Proc ... %@", proc);
+  if (verbose == YES)
-NSLog(@"Name ... %@", [proc processName]);
+    {
-NSLog(@"Files ... %@", files);
+      NSLog(@"Proc ... %@", proc);
+      NSLog(@"Name ... %@", [proc processName]);
+      NSLog(@"Files ... %@", files);
+    }
   for (i = 1; i < count; i++)
     {
       NSString *arg = [files objectAtIndex: i];
@@ -484,6 +494,8 @@ NSLog(@"Files ... %@", files);
       pool = [NSAutoreleasePool new];
 
       parser = [AGSParser new];
+      [parser setWordMap: [defs dictionaryForKey: @"WordMap"]];
+      [parser setVerbose: verbose];
       output = [AGSOutput new];
       if ([defs boolForKey: @"Standards"] == YES)
 	{