gnustep/libs-base
0
0
Fork 0
mirror of https://github.com/gnustep/libs-base.git synced 2025-05-30 08:21:25 +00:00
Code Issues Projects Releases Packages Wiki Activity

documentation fixes

Browse source 
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@32157 72102866-910b-0410-8b05-ffd578937521
This commit is contained in:
rfm 2011-02-14 10:57:57 +00:00
parent 3d7125e2b0
commit ea857575f2
17 changed files with 234 additions and 127 deletions
Download patch file Download diff file Expand all files Collapse all files

22
ChangeLog
View file

@ -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> 2011-02-14 Richard Frith-Macdonald <rfm@gnu.org>
* Headers/Foundation/NSPortCoder.h: * Headers/Foundation/NSPortCoder.h:

46
Documentation/coding-standards.texi
View file

@ -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)). where those spaces might be omitted ((eg. when brackets are doubled)).
This applies to square brackets too. 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 there is normally no space between the closing bracket and the following
expression or semicolon- expression or semicolon-
@example @example
@ -169,7 +171,7 @@ a = foo (ax, y, z);
@end example @end example
The placement of curly brackets is part of the indentation rules. the 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 @example
if (...) if (...)
@{ @{
@ -266,7 +268,7 @@ length limit).
@end example @end example
My own preference (not part of the standard in any way) is to 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 of code is involved
@example @example
if (a) if (a)
@ -290,15 +292,9 @@ the matching lines.
@node Memory Management, Error Handling, Coding Style, Top @node Memory Management, Error Handling, Coding Style, Top
@section Memory Management @section Memory Management
In anticipation of the day when we can make the use of a Garbage Collector We encourage the use of the following macros to ease retain and release
possible for all GNUstep apps (it's almost-usable/usable-with-care for and as a convenience for managing code which should work in both a
non-gui apps now), the normal use of retain/release/autorelease is garbage collecting and a retain counting environment.
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 -
@itemize @bullet @itemize @bullet
@item @item
ASSIGN(object,value) to assign an object variable, performing the appropriate retain/release as necessary. 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 @item
DESTROY(object) to release an object variable and set it to nil. DESTROY(object) to release an object variable and set it to nil.
@item @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 CREATE_AUTORELEASE_POOL(name) to create an autorelease pool with the
specified name. specified name.
@item IF_NO_GC(X) compile the code 'X' only if GarbageCollection is not @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 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 this is to use class version numbers to indicate which archive configuration
should be read. should be read.
Modern implementations are expected to suppoort keyed archiving and should
use the same keys that are used in OSX.
@c ****************************************************************** @c ******************************************************************
@node Documentation, Before You Commit, Object Persistence, Top @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 are so simple you might have to intentionally reword the documentation
so it is different. so it is different.
Currently there is a difference of opinion on whether to document in Public documentation should be in the header files, formatted so that the
the header or in the source file, although we generally lean towards autogsdoc tool can extract it.
the header currently. Make sure you are consistent with the current
method of documentation in the source file you are changing.
@c ****************************************************************** @c ******************************************************************
@node Before You Commit, Contributing, Documentation, Top @node Before You Commit, Contributing, Documentation, Top
@ -460,13 +450,17 @@ method of documentation in the source file you are changing.
@itemize @bullet @itemize @bullet
@item Make sure you have a ChangeLog entry @item Make sure you have a ChangeLog entry
@item Make sure everything still compiles @item Make sure any new method/class is documented in the header file.
@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}
or @file{Appkit/Appkit.h} if appropriate. 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 @item If you have updated and configure checks, be sure to run both
autoconf and autoheader. 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 @end itemize

5
Headers/Additions/GNUstepBase/GSMime.h
View file

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

9
Headers/Foundation/NSBundle.h
View file

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

3
Headers/Foundation/NSConnection.h
View file

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

26
Headers/Foundation/NSFileHandle.h
View file

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

15
Headers/Foundation/NSObjCRuntime.h
View file

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

2
Headers/Foundation/NSPropertyList.h
View file

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

2
Source/Additions/GSMime.m
View file

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

6
Source/Additions/GSObjCRuntime.m
View file

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

48
Source/DocMakefile
View file

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

4
Source/GSInternal.h
View file

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

2
Source/NSConnection.m
View file

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

6
Source/NSDateFormatter.m
View file

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

32
Source/NSFileManager.m
View file

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

104
Tools/AGSParser.m
View file

@ -1400,7 +1400,8 @@ recheck:
[d setObject: s forKey: @"Name"]; [d setObject: s forKey: @"Name"];
} }
/* We parse enum comment of the form: /* 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] == '{') if (isEnum && [self parseSpace] < length && buffer[pos] == '{')
{ {
NSString *ident; NSString *ident;
@ -1421,42 +1422,41 @@ recheck:
// let AGSOutput generate the deflist. // 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,
- <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]; 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' /* Skip the left-hand side such as ' = aValue'
*/
Four combinations can be parsed: while (pos < length && buffer[pos] != ',' && buffer[pos] != '}')
- fieldDecl,
- fieldDelc, <comment>
- fieldDecl }
- fieldDelc <comment> } */
while (buffer[pos] != ',' && buffer[pos] != '}')
{ {
BOOL foundComment = (buffer[pos] == '/' && buffer[pos + 1] == '*');
if (foundComment)
break;
pos++; pos++;
} }
if (buffer[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++; pos++;
}
[self parseSpace]; /* Parse doc comment into 'comment' ivar */
[fieldComments appendString: @"<term><em>"];
if (comment != nil)
foundFieldComment = YES;
if (ident != nil) if (ident != nil)
{ {
[fieldComments appendString: @"<term><em>"];
[fieldComments appendString: ident]; [fieldComments appendString: ident];
[fieldComments appendString: @"</em></term>"]; [fieldComments appendString: @"</em></term>"];
[fieldComments appendString: @"<desc>"]; [fieldComments appendString: @"<desc>"];
@ -2430,7 +2430,6 @@ try:
RELEASE(tmp); RELEASE(tmp);
if ([val length] > 0) if ([val length] > 0)
{ {
if ([val isEqualToString: @"//"] == YES) if ([val isEqualToString: @"//"] == YES)
{ {
[self skipToEndOfLine]; [self skipToEndOfLine];
@ -2555,6 +2554,11 @@ fail:
dict = [[NSMutableDictionary alloc] initWithCapacity: 4]; dict = [[NSMutableDictionary alloc] initWithCapacity: 4];
[self parseSpace: spaces]; [self parseSpace: spaces];
name = [self parseIdentifier]; name = [self parseIdentifier];
if (nil == name)
{
// [self log: @"Missing name in #define"];
return nil;
}
[self parseSpace: spaces]; [self parseSpace: spaces];
if (pos < length && buffer[pos] == '(') if (pos < length && buffer[pos] == '(')
{ {
@ -2711,6 +2715,30 @@ fail:
while (buffer[pos] != term) while (buffer[pos] != term)
{ {
token = [self parseIdentifier]; 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) if ([self parseSpace] >= length)
{ {
[self log: @"error at method name component"]; [self log: @"error at method name component"];
@ -2924,7 +2952,8 @@ fail:
if (orderedSymbolDecls == nil) if (orderedSymbolDecls == nil)
{ {
orderedSymbolDecls = [NSMutableArray array]; orderedSymbolDecls = [NSMutableArray array];
[orderedSymbolDeclsByUnit setObject: orderedSymbolDecls forKey: aUnitName]; [orderedSymbolDeclsByUnit setObject: orderedSymbolDecls
forKey: aUnitName];
} }
[orderedSymbolDecls addObject: aMethodOrFunc]; [orderedSymbolDecls addObject: aMethodOrFunc];
} }
@ -2935,6 +2964,7 @@ fail:
NSMutableDictionary *method; NSMutableDictionary *method;
NSMutableDictionary *exist; NSMutableDictionary *exist;
NSString *token; NSString *token;
BOOL optionalMethods = NO;
if (flag == YES) if (flag == YES)
{ {
@ -2987,6 +3017,10 @@ fail:
{ {
return nil; return nil;
} }
if (YES == optionalMethods)
{
[method setObject: @"YES" forKey: @"Optional"];
}
token = [method objectForKey: @"Name"]; token = [method objectForKey: @"Name"];
if (flag == YES) if (flag == YES)
{ {
@ -3074,6 +3108,20 @@ fail:
{ {
return methods; 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) else if ([token isEqual: @"class"] == YES)
{ {
/* /*

23
Tools/DocMakefile
View file

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