documentation fixes

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

ChangeLog

@@ -1,3 +1,25 @@
+2011-02-14  Richard Frith-Macdonald <rfm@gnu.org>
+
+	* Source/NSFileManager.m:
+	* Source/GSInternal.h:
+	* Source/DocMakefile:
+	* Source/Additions/GSMime.m:
+	* Source/Additions/GSObjCRuntime.m:
+	* Source/NSConnection.m:
+	* Source/NSDateFormatter.m:
+	* Documentation/coding-standards.texi:
+	* Headers/Foundation/NSBundle.h:
+	* Headers/Foundation/NSPropertyList.h:
+	* Headers/Foundation/NSConnection.h:
+	* Headers/Foundation/NSObjCRuntime.h:
+	* Headers/Foundation/NSFileHandle.h:
+	* Headers/Additions/GNUstepBase/GSMime.h:
+	* Tools/DocMakefile:
+	* Tools/AGSParser.m:
+	Documentation cleanups and fixes ... add new macros to list of symbols
+	to ignore.  Add support for @optional and @required. Add support for
+	method attributes.
+
 2011-02-14  Richard Frith-Macdonald <rfm@gnu.org>
 
 	* Headers/Foundation/NSPortCoder.h:

Documentation/coding-standards.texi

@@ -159,7 +159,9 @@ the trailing bracket (as in this example), though there are odd occasions
 where those spaces might be omitted ((eg. when brackets are doubled)).
 This applies to square brackets too.
 
-Where round brackets are used for type-casts or at the end of a statement,
+Where round brackets are used to enclose function or macro paramters, there
+is no space between the function romacro name and the opening bracket, and
+where round brackets are used for type-casts or at the end of a statement,
 there is normally no space between the closing bracket and the following
 expression or semicolon-
 @example
@@ -169,7 +171,7 @@ a = foo (ax, y, z);
 @end example
 
 The placement of curly brackets is part of the indentation rules. the
-correct GNU style is
+correct GNU style is to indent by two spaces
 @example
   if (...)
     @{
@@ -266,7 +268,7 @@ length limit).
 @end example
 
 My own preference (not part of the standard in any way) is to
-generally use curly brackets for control constructs, event where only one line
+generally use curly brackets for control constructs, even where only one line
 of code is involved
 @example
   if (a)
@@ -290,15 +292,9 @@ the matching lines.
 @node Memory Management, Error Handling, Coding Style, Top
 @section Memory Management
 
-In anticipation of the day when we can make the use of a Garbage Collector
-possible for all GNUstep apps (it's almost-usable/usable-with-care for
-non-gui apps now), the normal use of retain/release/autorelease is
-deprecated.
-
-You should always use the macros RETAIN(), RELEASE() and AUTORELEASE()
-(defined in NSObject.h) instead.
-
-There are also some extra macros that may be of use -
+We encourage the use of the following macros to ease retain and release
+and as a convenience for managing code which should work in both a
+garbage collecting and a retain counting environment.
 @itemize @bullet
 @item
 ASSIGN(object,value) to assign an object variable, performing the appropriate retain/release as necessary.
@@ -307,12 +303,6 @@ ASSIGNCOPY(object,value) to copy the value and assign it to the object.
 @item
 DESTROY(object) to release an object variable and set it to nil.
 @item
-TEST_RETAIN(object) to retain an object if it is non-nil
-@item
-TEST_RELEASE(object) to release an object if it is non-nil
-@item
-TEST_AUTORELEASE(object) to autorelease an object if it is non-nil
-@item
 CREATE_AUTORELEASE_POOL(name) to create an autorelease pool with the
 specified name.
 @item IF_NO_GC(X) compile the code 'X' only if GarbageCollection is not
@@ -438,6 +428,8 @@ that all changes to these methods be backward compatible with previously
 stored archives (for instance, those created by Gorm). The easiest way to do
 this is to use class version numbers to indicate which archive configuration
 should be read.
+Modern implementations are expected to suppoort keyed archiving and should
+use the same keys that are used in OSX.
 
 @c ******************************************************************
 @node Documentation, Before You Commit, Object Persistence, Top
@@ -449,10 +441,8 @@ do not copy either the OpenStep or Cocoa documentation. Some methods
 are so simple you might have to intentionally reword the documentation
 so it is different.
 
-Currently there is a difference of opinion on whether to document in
-the header or in the source file, although we generally lean towards
-the header currently. Make sure you are consistent with the current
-method of documentation in the source file you are changing.
+Public documentation should be in the header files, formatted so that the
+autogsdoc tool can extract it.
 
 @c ******************************************************************
 @node Before You Commit, Contributing, Documentation, Top
@@ -460,13 +450,17 @@ method of documentation in the source file you are changing.
 
 @itemize @bullet
 @item Make sure you have a ChangeLog entry
-@item Make sure everything still compiles
-@item Make sure you've tested the change as much as is reasonable.
-@item If you have added a class, add the class to @file{Foundation/Foundation.h}
+@item Make sure any new method/class is documented in the header file.
 or @file{Appkit/Appkit.h} if appropriate.
-@item Documentation the methods you have changed or added.
+@item If you have added a class, add the class to @file{Foundation/Foundation.h}
 @item If you have updated and configure checks, be sure to run both
 autoconf and autoheader.
+@item Make sure everything still compiles at least on the most common
+platform (ie Intel processor, GNU/Linux operating system, with the GCC compiler and ObjC runtime), and ideally on ms-windows too.
+@item Make sure you've tested the change and contributed testcase code to
+the testsuite. Run the testsuite on the systems where you compiled.
+@item Make sure that documentation generation still works by running 'make'
+in the Documentation directory.
 @end itemize
 
 

Headers/Additions/GNUstepBase/GSMime.h

@@ -293,8 +293,9 @@ typedef enum {
 @interface	GSMimeSMTPClient : NSObject
 {
 #if	GS_NONFRAGILE
-#  if	defined(GSMimeSMTPClient_IVARS)
-@public GSMimeSMTPClient_IVARS
+#  if	defined(GS_GSMimeSMTPClient_IVARS)
+@public
+GS_GSMimeSMTPClient_IVARS;
 #  endif
 #else
 @private id _internal;

Headers/Foundation/NSBundle.h

@@ -305,13 +305,16 @@ GS_EXPORT NSString* const NSLoadedClasses;
    localized equivalent found.  This can be useful during development to check
    where a given string in the UI is "coming from".</p>
  */
+#ifdef __clang__
 - (NSString*) localizedStringForKey: (NSString*)key
 			      value: (NSString*)value
 			      table: (NSString*)tableName
-#ifdef __clang__
-				  __attribute__((format_arg(1)))
+				  __attribute__((format_arg(1)));
+#else
+- (NSString*) localizedStringForKey: (NSString*)key
+			      value: (NSString*)value
+			      table: (NSString*)tableName;
 #endif
-	;
 
 /** Returns the absolute path to the resources directory of the bundle.  */
 - (NSString*) resourcePath;

Headers/Foundation/NSConnection.h

@@ -96,7 +96,8 @@ GS_EXPORT NSString* const NSConnectionProxyCount;	/* Objects received */
 {
 #if	GS_NONFRAGILE
 #  if	defined(GS_NSConnection_IVARS)
-@public GS_NSConnection_IVARS
+@public
+GS_NSConnection_IVARS;
 #  endif
 #else
 @private id _internal;

Headers/Foundation/NSFileHandle.h

@@ -181,19 +181,19 @@ GS_EXPORT NSString * const NSFileHandleOperationException;
 // GNUstep class extensions
 
 @interface NSFileHandle (GNUstepExtensions)
-+ (id) fileHandleAsServerAtAddress: (NSString*)a
-			   service: (NSString*)s
-			  protocol: (NSString*)p;
-+ (id) fileHandleAsClientAtAddress: (NSString*)a
-			   service: (NSString*)s
-			  protocol: (NSString*)p;
-+ (id) fileHandleAsClientInBackgroundAtAddress: (NSString*)a
-				       service: (NSString*)s
-				      protocol: (NSString*)p;
-+ (id) fileHandleAsClientInBackgroundAtAddress: (NSString*)a
-				       service: (NSString*)s
-				      protocol: (NSString*)p
-				      forModes: (NSArray*)m;
++ (id) fileHandleAsServerAtAddress: (NSString*)address
+			   service: (NSString*)service
+			  protocol: (NSString*)protocol;
++ (id) fileHandleAsClientAtAddress: (NSString*)address
+			   service: (NSString*)service
+			  protocol: (NSString*)protocol;
++ (id) fileHandleAsClientInBackgroundAtAddress: (NSString*)address
+				       service: (NSString*)service
+				      protocol: (NSString*)protocol;
++ (id) fileHandleAsClientInBackgroundAtAddress: (NSString*)address
+				       service: (NSString*)service
+				      protocol: (NSString*)protocol
+				      forModes: (NSArray*)modes;
 - (void) readDataInBackgroundAndNotifyLength: (unsigned)len;
 - (void) readDataInBackgroundAndNotifyLength: (unsigned)len
 				    forModes: (NSArray*)modes;

Headers/Foundation/NSObjCRuntime.h

@@ -61,17 +61,14 @@ extern "C" {
 
 enum 
 {
-  /**
-   * Specifies that the enumeration is concurrency-safe.  Note that this does
-   * not mean that it will be carried out in a concurrent manner, only that
-   * it can be.
+  NSEnumerationConcurrent = (1UL << 0), /** Specifies that the enumeration
+   * is concurrency-safe.  Note that this does not mean that it will be
+   * carried out in a concurrent manner, only that it can be.
    */
-  NSEnumerationConcurrent = (1UL << 0),
-  /**
-   * Specifies that the enumeration should happen in the opposite of the
-   * natural order of the collection.
+
+  NSEnumerationReverse = (1UL << 1) /** Specifies that the enumeration should
+   * happen in the opposite of the natural order of the collection.
    */
-  NSEnumerationReverse = (1UL << 1)
 };
 
 /** Bitfield used to specify options to control enumeration over collections.

Headers/Foundation/NSPropertyList.h

@@ -274,7 +274,7 @@ typedef NSUInteger NSPropertyListFormat;
                       options: (NSPropertyListReadOptions)anOption
                        format: (NSPropertyListFormat*)aFormat
                         error: (NSError**)error;
-+ (NSInteger) writePropertyList: (id)plist
++ (NSInteger) writePropertyList: (id)aPropertyList
                        toStream: (NSOutputStream*)stream
                          format: (NSPropertyListFormat)aFormat
                         options: (NSPropertyListWriteOptions)anOption

Source/Additions/GSMime.m

@@ -79,7 +79,7 @@
   unsigned		woffset;\
   BOOL			readable;\
   BOOL			writable;\
-  int			cState;\
+  int			cState
 
 
 #include <string.h>

Source/Additions/GSObjCRuntime.m

@@ -469,15 +469,15 @@ GSObjCAddClasses(NSArray *classes)
 static BOOL behavior_debug = NO;
 
 BOOL
-GSObjCBehaviorDebug(int i)
+GSObjCBehaviorDebug(int setget)
 {
   BOOL	old = behavior_debug;
 
-  if (i == YES)
+  if (setget == 1)
     {
       behavior_debug = YES;
     }
-  else if (i == NO)
+  else if (setget == 0)
     {
       behavior_debug = NO;
     }

Source/DocMakefile

@@ -185,13 +185,27 @@ Base_AGSDOC_FLAGS = \
 	-TypedefsTemplate TypesAndConstants \
 	-VariablesTemplate TypesAndConstants \
 	-WordMap '{\
-	FOUNDATION_EXPORT=extern;FOUNDATION_STATIC_INLINE="";\
+	DEFINE_BLOCK_TYPE="//";\
+	FOUNDATION_EXPORT=extern;\
+	FOUNDATION_STATIC_INLINE="";\
+	GS_ATTRIB_DEPRECATED="";\
+	GS_DECLARE="";\
+	GS_EXPORT=extern;\
+	GS_GEOM_ATTR="";\
+	GS_GEOM_SCOPE=extern;\
+	GS_NORETURN_METHOD="";\
+	GS_PRIVATE_INTERNAL="//";\
+	GS_RANGE_ATTR="";\
+	GS_RANGE_SCOPE=extern;\
 	GS_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="";\
+	GS_UNUSED_IVAR="";\
+	GS_ZONE_ATTR="";\
+	GS_ZONE_SCOPE=extern;\
 	INLINE=inline;\
+	NS_CONSUMED="";\
+	NS_CONSUMES_SELF="";\
+	NS_RETURNS_NOT_RETAINED="";\
+	NS_RETURNS_RETAINED="";\
 	WINAPI="";\
 	}' -Up Base
 
@@ -208,14 +222,28 @@ BaseAdditions_AGSDOC_FLAGS = \
 	-TypedefsTemplate TypesAndConstants \
 	-VariablesTemplate TypesAndConstants \
 	-WordMap '{\
-	FOUNDATION_EXPORT=extern;FOUNDATION_STATIC_INLINE="";\
+	DEFINE_BLOCK_TYPE="//";\
+	FOUNDATION_EXPORT=extern;\
+	FOUNDATION_STATIC_INLINE="";\
 	GS_ATTRIB_DEPRECATED="";\
+	GS_DECLARE="";\
+	GS_EXPORT=extern;\
+	GS_GEOM_ATTR="";\
+	GS_GEOM_SCOPE=extern;\
+	GS_NORETURN_METHOD="";\
+	GS_PRIVATE_INTERNAL="//";\
+	GS_RANGE_ATTR="";\
+	GS_RANGE_SCOPE=extern;\
 	GS_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="";\
+	GS_UNUSED_IVAR="";\
+	GS_ZONE_ATTR="";\
+	GS_ZONE_SCOPE=extern;\
 	INLINE=inline;\
+	NS_CONSUMED="";\
+	NS_CONSUMES_SELF="";\
+	NS_RETURNS_NOT_RETAINED="";\
+	NS_RETURNS_RETAINED="";\
+	WINAPI="";\
 	}' -Up BaseAdditions
 
 # Use local version of autogsdoc in case it is not installed

Source/GSInternal.h

@@ -31,7 +31,7 @@
  * form:
  * #if	GS_NONFRAGILE
  * #  if defined(GS_X_IVARS)
- * @public GS_X_IVARS
+ * @public GS_X_IVARS;
  * #  endif
  * #else
  * @private id _internal;
@@ -70,7 +70,7 @@
 @interface	name ## Internal : NSObject \
 { \
 @public \
-GS_##name##_IVARS \
+GS_##name##_IVARS; \
 } \
 @end \
 @implementation	name ## Internal \

Source/NSConnection.m

@@ -64,7 +64,7 @@
   NSString		*_remoteName; \
   NSString		*_registeredName; \
   NSPortNameServer	*_nameServer; \
-  int			_lastKeepalive;
+  int			_lastKeepalive
 
 #define	EXPOSE_NSDistantObject_IVARS	1
 

Source/NSDateFormatter.m

@@ -873,7 +873,7 @@ static NSDateFormatterBehavior _defaultBehavior = 0;
   return result;
 }
 
-+ (NSString *) dateFormatFromTemplate: (NSString *) template
++ (NSString *) dateFormatFromTemplate: (NSString *) aTemplate
                               options: (NSUInteger) opts
                                locale: (NSLocale *) locale
 {
@@ -889,9 +889,9 @@ static NSDateFormatterBehavior _defaultBehavior = 0;
   if (U_FAILURE(err))
     return nil;
   
-  if ((patLen = [template length]) > BUFFER_SIZE)
+  if ((patLen = [aTemplate length]) > BUFFER_SIZE)
     patLen = BUFFER_SIZE;
-  [template getCharacters: pat range: NSMakeRange(0, patLen)];
+  [aTemplate getCharacters: pat range: NSMakeRange(0, patLen)];
   
   skelLen = udatpg_getSkeleton (datpg, pat, patLen, skel, BUFFER_SIZE, &err);
   if (U_FAILURE(err))

Source/NSFileManager.m

@@ -1721,22 +1721,22 @@ static NSStringEncoding	defaultEncoding;
  *   use the accessor methods where they are available.
  * </p>
  * <list>
- *   <item>[NSDictionary-fileCreationDate]</item>
- *   <item>[NSDictionary-fileExtensionHidden]</item>
- *   <item>[NSDictionary-fileHFSCreatorCode]</item>
- *   <item>[NSDictionary-fileHFSTypeCode]</item>
- *   <item>[NSDictionary-fileIsAppendOnly]</item>
- *   <item>[NSDictionary-fileIsImmutable]</item>
- *   <item>[NSDictionary-fileSize]</item>
- *   <item>[NSDictionary-fileType]</item>
- *   <item>[NSDictionary-fileOwnerAccountName]</item>
- *   <item>[NSDictionary-fileOwnerAccountID]</item>
- *   <item>[NSDictionary-fileGroupOwnerAccountName]</item>
- *   <item>[NSDictionary-fileGroupOwnerAccountID]</item>
- *   <item>[NSDictionary-fileModificationDate]</item>
- *   <item>[NSDictionary-filePosixPermissions]</item>
- *   <item>[NSDictionary-fileSystemNumber]</item>
- *   <item>[NSDictionary-fileSystemFileNumber]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileCreationDate]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileExtensionHidden]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileHFSCreatorCode]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileHFSTypeCode]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileIsAppendOnly]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileIsImmutable]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileSize]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileType]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileOwnerAccountName]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileOwnerAccountID]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileGroupOwnerAccountName]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileGroupOwnerAccountID]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileModificationDate]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-filePosixPermissions]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileSystemNumber]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileSystemFileNumber]</item>
  * </list>
  */
 - (NSDictionary*) fileAttributesAtPath: (NSString*)path traverseLink: (BOOL)flag

Tools/AGSParser.m

@@ -1400,7 +1400,8 @@ recheck:
 	  [d setObject: s forKey: @"Name"];
 	}
       /* We parse enum comment of the form:
-         <introComment> enum { field1, <comment1> field2 <comment2> } bla; */
+       * <introComment> enum { <comment1> field1, <comment2> field2 } bla;
+       */
       if (isEnum && [self parseSpace] < length && buffer[pos] == '{')
 	{
           NSString *ident;
@@ -1421,42 +1422,41 @@ recheck:
           // let AGSOutput generate the deflist.
 	  while (buffer[pos] != '}')
             {
+	      /*
+		 A comment belongs with the declaration following it,
+		 unless it begins on the same line as a declaration.
+                 Six combinations can be parsed:
+                 - fieldDecl,
+                 - <comment> fieldDecl,
+                 - fieldDecl, <comment>
+                 - <comment> fieldDecl, <comment>
+                 - fieldDecl }
+                 - <comment> fieldDecl }
+	       */
+
+	      /* Parse any space and comments before the identifier into
+	       * 'comment' and get the identifier in 'ident'.
+	       */
               ident = [self parseIdentifier];
-              /* Discard any comment parsed before the identifier */
-              if (comment != nil)
-                {
-                  [self log: @"Ignoring comment before first field %@ in %@", 
-                    comment, ident, s];
-                  DESTROY(comment);
-                }
 
               /* Skip the left-hand side such as ' = aValue'
-
-                 Four combinations can be parsed:
-                 - fieldDecl,
-                 - fieldDelc, <comment> 
-                 - fieldDecl }
-                 - fieldDelc <comment> } */
-              while (buffer[pos] != ',' && buffer[pos] != '}')
+	       */
+              while (pos < length && buffer[pos] != ',' && buffer[pos] != '}')
                 {
-                  BOOL foundComment = (buffer[pos] == '/' && buffer[pos + 1] == '*');
-
-                  if (foundComment)
-                    break;
-
                   pos++;
                 }
               if (buffer[pos] == ',')
+		{
+                  /* Parse any more space on the same line as the identifier
+		   * appending it to the 'comment' ivar
+		   */
+		  [self parseSpace: spaces];
                   pos++;
-
-              [self parseSpace]; /* Parse doc comment into 'comment' ivar */
-
-              [fieldComments appendString: @"<term><em>"];
-              if (comment != nil)
-                foundFieldComment = YES;
+		}
 
               if (ident != nil)
                 {
+                  [fieldComments appendString: @"<term><em>"];
                   [fieldComments appendString: ident];
                   [fieldComments appendString: @"</em></term>"];
                   [fieldComments appendString: @"<desc>"];
@@ -2430,7 +2430,6 @@ try:
 	  RELEASE(tmp);
 	  if ([val length] > 0)
 	    {
-	
 	      if ([val isEqualToString: @"//"] == YES)
 		{
 		  [self skipToEndOfLine];
@@ -2555,6 +2554,11 @@ fail:
   dict = [[NSMutableDictionary alloc] initWithCapacity: 4];
   [self parseSpace: spaces];
   name = [self parseIdentifier];
+  if (nil == name)
+    {
+      // [self log: @"Missing name in #define"];
+      return nil;
+    }
   [self parseSpace: spaces];
   if (pos < length && buffer[pos] == '(')
     {
@@ -2711,6 +2715,30 @@ fail:
   while (buffer[pos] != term)
     {
       token = [self parseIdentifier];
+      if ([token isEqual: @"__attribute__"] == YES)
+	{
+	  if ([self skipSpaces] < length && buffer[pos] == '(')
+	    {
+	      unsigned	start = pos;
+	      NSString	*attr;
+
+	      [self skipBlock];	// Skip the attributes
+	      attr = [NSString stringWithCharacters: buffer + start
+					     length: pos - start];
+	      if ([attr rangeOfString: @"deprecated"].length > 0)
+		{
+		  [self appendComment: @"<em>Warning</em> this is "
+		    @"<em>deprecated</em> and may be removed in "
+		    @"future versions"
+		    to: nil];
+		}
+	    }
+	  else
+	    {
+	      [self log: @"strange format function attributes"];
+	    }
+	  continue;
+	}
       if ([self parseSpace] >= length)
 	{
 	  [self log: @"error at method name component"];
@@ -2924,7 +2952,8 @@ fail:
   if (orderedSymbolDecls == nil)
     {
       orderedSymbolDecls = [NSMutableArray array];
-      [orderedSymbolDeclsByUnit setObject: orderedSymbolDecls forKey: aUnitName];
+      [orderedSymbolDeclsByUnit setObject: orderedSymbolDecls
+				   forKey: aUnitName];
     }
   [orderedSymbolDecls addObject: aMethodOrFunc];
 }
@@ -2935,6 +2964,7 @@ fail:
   NSMutableDictionary	*method;
   NSMutableDictionary	*exist;
   NSString		*token;
+  BOOL			optionalMethods = NO;
 
   if (flag == YES)
     {
@@ -2987,6 +3017,10 @@ fail:
 	      {
 		return nil;
 	      }
+	    if (YES == optionalMethods)
+	      {
+		[method setObject: @"YES" forKey: @"Optional"];
+	      }
 	    token = [method objectForKey: @"Name"];
 	    if (flag == YES)
 	      {
@@ -3074,6 +3108,20 @@ fail:
 	      {
 		return methods;
 	      }
+	    else if ([token isEqual: @"optional"] == YES)
+	      {
+	        /* marking remaining methods as optional.
+	         */
+		optionalMethods = YES;
+		continue;
+	      }
+	    else if ([token isEqual: @"required"] == YES)
+	      {
+	        /* marking remaining methods as required.
+	         */
+		optionalMethods = NO;
+		continue;
+	      }
 	    else if ([token isEqual: @"class"] == YES)
 	      {
 		/*

Tools/DocMakefile

@@ -66,13 +66,26 @@ BaseTools_AGSDOC_FLAGS = \
 	-HeaderDirectory ../Tools \
 	-Standards YES \
 	-WordMap '{\
-	FOUNDATION_EXPORT=extern;FOUNDATION_STATIC_INLINE="";\
+	FOUNDATION_EXPORT=extern;\
+	FOUNDATION_STATIC_INLINE="";\
+	GS_ATTRIB_DEPRECATED="";\
+	GS_DECLARE="";\
+	GS_EXPORT=extern;\
+	GS_GEOM_ATTR="";\
+	GS_GEOM_SCOPE=extern;\
+	GS_NORETURN_METHOD="";\
+	GS_RANGE_ATTR="";\
+	GS_RANGE_SCOPE=extern;\
 	GS_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="";\
+	GS_UNUSED_IVAR="";\
+	GS_ZONE_ATTR="";\
+	GS_ZONE_SCOPE=extern;\
 	INLINE=inline;\
+	NS_CONSUMED="";\
+	NS_CONSUMES_SELF="";\
+	NS_RETURNS_NOT_RETAINED="";\
+	NS_RETURNS_RETAINED="";\
+	WINAPI="";\
 	}' -Up BaseTools
 
 # Use local version of autogsdoc in case it is not installed