Documentation generation improvments

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

ChangeLog

@@ -1,3 +1,11 @@
+2009-11-23 Richard Frith-Macdonald <rfm@gnu.org>
+
+	* Source/NSObject.m: Remove spurious semicolons
+	* Source/NSConnection.m: autogsdoc ignore confusing section
+	* Source/NSLock.m: autogsdoc ignore (just use header)
+	* Tools/AGSParser.m: add feature to ignore sections
+	* Tools/autogsdoc.m: document new ignore markup
+
 2009-11-04 Richard Frith-Macdonald <rfm@gnu.org>
 
 	* Source/NSAutoreleasePool.m: ([-drain]) Copy undocumented OSX behavior

Source/NSConnection.m

@@ -239,6 +239,8 @@ stringFromMsgType(int type)
 
 
 
+/** <ignore> */
+
 #define	GSInternal	NSConnectionInternal
 #include	"GSInternal.h"
 GS_BEGIN_INTERNAL(NSConnection)
@@ -312,6 +314,8 @@ GS_END_INTERNAL(NSConnection)
 #define	InameServer		(internal->_nameServer)
 #define	IlastKeepalive		(internal->_lastKeepalive)
 
+/** </ignore> */
+
 @interface NSConnection(Private)
 
 - (void) handlePortMessage: (NSPortMessage*)msg;

Source/NSLock.m

@@ -19,10 +19,10 @@
    Boston, MA 02111 USA.
 
    <title>NSLock class reference</title>
+   <ignore> All autogsdoc markup is in the header
 */
 
 
-
 // This file uses some SUS'98 extensions, so we need to tell glibc not to hide
 // them.  Other platforms have more sensible libcs, which just default to being
 // standards-compliant.
@@ -36,7 +36,7 @@
 #include <errno.h>
 #import "Foundation/NSException.h"
 
-/**
+/*
  * Methods shared between NSLock, NSRecursiveLock, and NSCondition
  *
  * Note: These methods currently throw exceptions when locks are incorrectly
@@ -126,7 +126,7 @@ static pthread_mutexattr_t attr_normal;
 static pthread_mutexattr_t attr_reporting;
 static pthread_mutexattr_t attr_recursive;
 
-/**
+/*
  * OS X 10.5 compatibility function to allow debugging deadlock conditions.
  */
 void _NSLockError(id obj, SEL _cmd)

Source/NSObject.m

@@ -1996,7 +1996,7 @@ GSGarbageCollectorLog(char *msg, GC_word arg)
   return NO;
 }
 
-+ (BOOL) resolveInstanceMethod: (SEL)name;
++ (BOOL) resolveInstanceMethod: (SEL)name
 {
   return NO;
 }
@@ -2029,7 +2029,7 @@ GSGarbageCollectorLog(char *msg, GC_word arg)
   return AUTORELEASE([[GSContentAccessingProxy alloc] initWithObject: self]);
 }
 
-- (id) forwardingTargetForSelector:(SEL)aSelector;
+- (id) forwardingTargetForSelector:(SEL)aSelector
 {
   return nil;
 }

Tools/AGSParser.m

@@ -367,6 +367,12 @@
       BOOL	isDocumentation = NO;
       BOOL	skippedFirstLine = NO;
       NSRange	r;
+      BOOL	ignore = NO;
+
+
+      /* Jump back here if we have ignored data up to a new comment.
+       */
+comment:
 
       pos += 2;	/* Skip opening part */
 
@@ -501,9 +507,32 @@
 	  if (end > start)
 	    {
 	      NSString	*tmp;
+	      NSRange	r;
 
 	      tmp = [NSString stringWithCharacters: start length: end - start];
-	      [self appendComment: tmp to: nil];
+recheck:
+	      if (YES == ignore)
+		{
+	          r = [tmp rangeOfString: @"</ignore>"];
+		  if (r.length > 0)
+		    {
+		      tmp = [tmp substringFromIndex: NSMaxRange(r)];
+		      ignore = NO;
+		    }
+		}
+	      if (NO == ignore)
+		{
+	          r = [tmp rangeOfString: @"<ignore>"];
+		  if (r.length > 0)
+		    {
+		      [self appendComment: [tmp substringToIndex: r.location]
+				       to: nil];
+		      tmp = [tmp substringFromIndex: NSMaxRange(r)];
+		      ignore = YES;
+		      goto recheck;
+		    }
+		  [self appendComment: tmp to: nil];
+		}
 	    }
 
           /*
@@ -927,6 +956,38 @@
 	    }
 	  commentsRead = YES;
 	}
+      if (YES == ignore)
+	{
+	  while (pos < length)
+	    {
+	      switch (buffer[pos])
+		{
+		  case '\'':
+		  case '"':
+		    [self skipLiteral];
+		    break;
+
+		  case '/':
+		    if (pos + 1 < length)
+		      {
+			if (buffer[pos + 1] == '/')
+			  {
+			    [self skipRemainderOfLine];
+			  }
+			else if (buffer[pos + 1] == '*')
+			  {
+			    goto comment;
+			  }
+		      }
+		    pos++;
+		    break;
+
+		  default:
+		    pos++;
+		    break;
+		}
+	    }
+	}
     }
   return pos;
 }

Tools/autogsdoc.m

@@ -86,7 +86,12 @@
       comment text is reformatted and then inserted into the output.<br />
       Where multiple comments are associated with the same item, they are
       joined together with a line break (&lt;br /&gt;) between each if
-      necessary.
+      necessary.<br />
+      Within a comment the special markup &lt;ignore&gt; and &lt;/ignore&gt;
+      may be used to tell autogsdoc to completely ignore the sourcecode
+      between these two pieces of markup (ie. the parser will skip from the
+      point just before it is told to start ignoring, to just after the point
+      where it is told to stop (or end of file if that occurs first).
     </p>
     <p>
       The tool can easily be used to document programs as well as libraries,