From ea857575f265af4b660f9c6e21848581cfb038de Mon Sep 17 00:00:00 2001 From: rfm Date: Mon, 14 Feb 2011 10:57:57 +0000 Subject: [PATCH] documentation fixes git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@32157 72102866-910b-0410-8b05-ffd578937521 --- ChangeLog | 22 +++++ Documentation/coding-standards.texi | 48 +++++------ Headers/Additions/GNUstepBase/GSMime.h | 5 +- Headers/Foundation/NSBundle.h | 11 ++- Headers/Foundation/NSConnection.h | 3 +- Headers/Foundation/NSFileHandle.h | 26 +++--- Headers/Foundation/NSObjCRuntime.h | 15 ++-- Headers/Foundation/NSPropertyList.h | 2 +- Source/Additions/GSMime.m | 2 +- Source/Additions/GSObjCRuntime.m | 6 +- Source/DocMakefile | 48 ++++++++--- Source/GSInternal.h | 4 +- Source/NSConnection.m | 2 +- Source/NSDateFormatter.m | 6 +- Source/NSFileManager.m | 32 ++++---- Tools/AGSParser.m | 106 ++++++++++++++++++------- Tools/DocMakefile | 23 ++++-- 17 files changed, 234 insertions(+), 127 deletions(-) diff --git a/ChangeLog b/ChangeLog index a1fa66dd4..4ef16d43d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,25 @@ +2011-02-14 Richard Frith-Macdonald + + * 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 * Headers/Foundation/NSPortCoder.h: diff --git a/Documentation/coding-standards.texi b/Documentation/coding-standards.texi index 366aa959f..8f774022a 100644 --- a/Documentation/coding-standards.texi +++ b/Documentation/coding-standards.texi @@ -159,17 +159,19 @@ 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 a = (int)b; - (void) methodWithArg1: (int)arg1 andArg2: (float)arg2; -a = foo (ax, y, z); +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 diff --git a/Headers/Additions/GNUstepBase/GSMime.h b/Headers/Additions/GNUstepBase/GSMime.h index 215231a3d..16136e686 100644 --- a/Headers/Additions/GNUstepBase/GSMime.h +++ b/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; diff --git a/Headers/Foundation/NSBundle.h b/Headers/Foundation/NSBundle.h index cdd24f1f0..9591c328b 100644 --- a/Headers/Foundation/NSBundle.h +++ b/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".

*/ +#ifdef __clang__ - (NSString*) localizedStringForKey: (NSString*)key value: (NSString*)value - table: (NSString*)tableName -#ifdef __clang__ - __attribute__((format_arg(1))) + table: (NSString*)tableName + __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; diff --git a/Headers/Foundation/NSConnection.h b/Headers/Foundation/NSConnection.h index 68c8d2a73..af3f74514 100644 --- a/Headers/Foundation/NSConnection.h +++ b/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; diff --git a/Headers/Foundation/NSFileHandle.h b/Headers/Foundation/NSFileHandle.h index 037f6cfef..cbe9adb19 100644 --- a/Headers/Foundation/NSFileHandle.h +++ b/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; diff --git a/Headers/Foundation/NSObjCRuntime.h b/Headers/Foundation/NSObjCRuntime.h index b04c00499..f7d9ea9fc 100644 --- a/Headers/Foundation/NSObjCRuntime.h +++ b/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. diff --git a/Headers/Foundation/NSPropertyList.h b/Headers/Foundation/NSPropertyList.h index 7307a93cc..594404f93 100644 --- a/Headers/Foundation/NSPropertyList.h +++ b/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 diff --git a/Source/Additions/GSMime.m b/Source/Additions/GSMime.m index d37a3f96c..168d55f1c 100644 --- a/Source/Additions/GSMime.m +++ b/Source/Additions/GSMime.m @@ -79,7 +79,7 @@ unsigned woffset;\ BOOL readable;\ BOOL writable;\ - int cState;\ + int cState #include diff --git a/Source/Additions/GSObjCRuntime.m b/Source/Additions/GSObjCRuntime.m index 8e3d94eb6..be1c585f0 100644 --- a/Source/Additions/GSObjCRuntime.m +++ b/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; } diff --git a/Source/DocMakefile b/Source/DocMakefile index dd8398ced..31ac98c14 100644 --- a/Source/DocMakefile +++ b/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 diff --git a/Source/GSInternal.h b/Source/GSInternal.h index 7901839ae..60f5f228a 100644 --- a/Source/GSInternal.h +++ b/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 \ diff --git a/Source/NSConnection.m b/Source/NSConnection.m index 4c60a318a..f95289616 100644 --- a/Source/NSConnection.m +++ b/Source/NSConnection.m @@ -64,7 +64,7 @@ NSString *_remoteName; \ NSString *_registeredName; \ NSPortNameServer *_nameServer; \ - int _lastKeepalive; + int _lastKeepalive #define EXPOSE_NSDistantObject_IVARS 1 diff --git a/Source/NSDateFormatter.m b/Source/NSDateFormatter.m index 0bb002e84..f120e4dc5 100644 --- a/Source/NSDateFormatter.m +++ b/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)) diff --git a/Source/NSFileManager.m b/Source/NSFileManager.m index e05927927..a1130701d 100644 --- a/Source/NSFileManager.m +++ b/Source/NSFileManager.m @@ -1721,22 +1721,22 @@ static NSStringEncoding defaultEncoding; * use the accessor methods where they are available. *

* - * [NSDictionary-fileCreationDate] - * [NSDictionary-fileExtensionHidden] - * [NSDictionary-fileHFSCreatorCode] - * [NSDictionary-fileHFSTypeCode] - * [NSDictionary-fileIsAppendOnly] - * [NSDictionary-fileIsImmutable] - * [NSDictionary-fileSize] - * [NSDictionary-fileType] - * [NSDictionary-fileOwnerAccountName] - * [NSDictionary-fileOwnerAccountID] - * [NSDictionary-fileGroupOwnerAccountName] - * [NSDictionary-fileGroupOwnerAccountID] - * [NSDictionary-fileModificationDate] - * [NSDictionary-filePosixPermissions] - * [NSDictionary-fileSystemNumber] - * [NSDictionary-fileSystemFileNumber] + * [NSDictionary(NSFileAttributes)-fileCreationDate] + * [NSDictionary(NSFileAttributes)-fileExtensionHidden] + * [NSDictionary(NSFileAttributes)-fileHFSCreatorCode] + * [NSDictionary(NSFileAttributes)-fileHFSTypeCode] + * [NSDictionary(NSFileAttributes)-fileIsAppendOnly] + * [NSDictionary(NSFileAttributes)-fileIsImmutable] + * [NSDictionary(NSFileAttributes)-fileSize] + * [NSDictionary(NSFileAttributes)-fileType] + * [NSDictionary(NSFileAttributes)-fileOwnerAccountName] + * [NSDictionary(NSFileAttributes)-fileOwnerAccountID] + * [NSDictionary(NSFileAttributes)-fileGroupOwnerAccountName] + * [NSDictionary(NSFileAttributes)-fileGroupOwnerAccountID] + * [NSDictionary(NSFileAttributes)-fileModificationDate] + * [NSDictionary(NSFileAttributes)-filePosixPermissions] + * [NSDictionary(NSFileAttributes)-fileSystemNumber] + * [NSDictionary(NSFileAttributes)-fileSystemFileNumber] * */ - (NSDictionary*) fileAttributesAtPath: (NSString*)path traverseLink: (BOOL)flag diff --git a/Tools/AGSParser.m b/Tools/AGSParser.m index 1bf066704..14b72f4f9 100644 --- a/Tools/AGSParser.m +++ b/Tools/AGSParser.m @@ -1400,7 +1400,8 @@ recheck: [d setObject: s forKey: @"Name"]; } /* We parse enum comment of the form: - enum { field1, field2 } bla; */ + * enum { field1, field2 } bla; + */ if (isEnum && [self parseSpace] < length && buffer[pos] == '{') { NSString *ident; @@ -1419,44 +1420,43 @@ recheck: // TODO: We should put the parsed field into the doc index and // let AGSOutput generate the deflist. - while (buffer[pos] != '}') + 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, + - fieldDecl, + - fieldDecl, + - fieldDecl, + - fieldDecl } + - 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, - - fieldDecl } - - fieldDelc } */ - 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: @""]; - if (comment != nil) - foundFieldComment = YES; + } if (ident != nil) { + [fieldComments appendString: @""]; [fieldComments appendString: ident]; [fieldComments appendString: @""]; [fieldComments appendString: @""]; @@ -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: @"Warning this is " + @"deprecated 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) { /* diff --git a/Tools/DocMakefile b/Tools/DocMakefile index 71f50dde0..8cf143174 100644 --- a/Tools/DocMakefile +++ b/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