From bda35fceb3410591a51297fe442939a00da3f513 Mon Sep 17 00:00:00 2001 From: Adrian Robert Date: Tue, 22 Jun 2004 22:40:40 +0000 Subject: [PATCH] added GSdoc comments to class, method, and function declarations; for some classes some comments were already in the source file (not the header), in which case further comments were added here; otherwise comments were put in the headers git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@19588 72102866-910b-0410-8b05-ffd578937521 --- Source/Additions/GSCategories.m | 48 +- Source/Additions/Unicode.m | 2 +- Source/GSString.m | 2 +- Source/GSTcpPort.m | 2 +- Source/NSArchiver.m | 62 ++- Source/NSArray.m | 20 +- Source/NSAttributedString.m | 98 +++- Source/NSBitmapCharSet.m | 2 +- Source/NSCalendarDate.m | 4 +- Source/NSCharacterSet.m | 68 ++- Source/NSClassDescription.m | 23 +- Source/NSCoder.m | 2 + Source/NSCountedSet.m | 40 +- Source/NSData.m | 163 ++++++- Source/NSDate.m | 12 +- Source/NSDecimal.m | 15 +- Source/NSDecimalNumber.m | 1 + Source/NSDictionary.m | 111 ++++- Source/NSDistantObject.m | 3 + Source/NSDistributedLock.m | 5 + Source/NSDistributedNotificationCenter.m | 42 +- Source/NSEnumerator.m | 11 + Source/NSException.m | 25 +- Source/NSFileHandle.m | 120 ++++- Source/NSFileManager.m | 106 +++-- Source/NSHashTable.m | 4 +- Source/NSIndexSet.m | 4 +- Source/NSInvocation.m | 14 +- Source/NSKeyedArchiver.m | 6 +- Source/NSKeyedUnarchiver.m | 3 + Source/NSLock.m | 19 +- Source/NSMapTable.m | 2 +- Source/NSMessagePort.m | 9 +- Source/NSMessagePortNameServer.m | 10 +- Source/NSNotification.m | 24 +- Source/NSNotificationCenter.m | 55 ++- Source/NSNotificationQueue.m | 47 ++ Source/NSNumber.m | 39 -- Source/NSNumberFormatter.m | 1 + Source/NSObject.m | 105 ++++- Source/NSPort.m | 4 + Source/NSProcessInfo.m | 12 + Source/NSProtocolChecker.m | 26 +- Source/NSProxy.m | 23 +- Source/NSRunLoop.m | 49 +- Source/NSScanner.m | 6 +- Source/NSSet.m | 90 +++- Source/NSSocketPort.m | 2 +- Source/NSString.m | 573 ++++++++++++++++------- Source/NSThread.m | 13 +- Source/NSTimeZone.m | 12 +- Source/NSTimer.m | 8 + Source/NSURL.m | 5 +- Source/NSUnarchiver.m | 91 +++- Source/NSUndoManager.m | 12 +- Source/externs.m | 5 +- 56 files changed, 1744 insertions(+), 516 deletions(-) diff --git a/Source/Additions/GSCategories.m b/Source/Additions/GSCategories.m index ec9b39d9e..bd1f1edc0 100644 --- a/Source/Additions/GSCategories.m +++ b/Source/Additions/GSCategories.m @@ -93,7 +93,7 @@ /** - * Extension methods for the NSData class + * Extension methods for the NSData class. */ @implementation NSData (GSCategories) @@ -1196,29 +1196,6 @@ newLockAt(Class self, SEL _cmd, id *location) @implementation NSLock (GSCategories) -/** - * Initializes the id pointed to by location - * with a new instance of the receiver's class - * in a thread safe manner, unless - * it has been previously initialized. - * Returns the contents pointed to by location. - * The location is considered unintialized if it contains nil. - *
- * This method is used in the GS_INITIALIZED_LOCK macro - * to initialize lock variables when it cannot be insured - * that they can be initialized in a thread safe environment. - * - * NSLock *my_lock = nil; - * - * void function (void) - * { - * [GS_INITIALIZED_LOCK(my_lock, NSLock) lock]; - * do_work (); - * [my_lock unlock]; - * } - * - * - */ + (id) newLockAt: (id *)location { return newLockAt(self, _cmd, location); @@ -1226,29 +1203,6 @@ newLockAt(Class self, SEL _cmd, id *location) @end @implementation NSRecursiveLock (GSCategories) -/** - * Initializes the id pointed to by location - * with a new instance of the receiver's class - * in a thread safe manner, unless - * it has been previously initialized. - * Returns the contents pointed to by location. - * The location is considered unintialized if it contains nil. - *
- * This method is used in the GS_INITIALIZED_LOCK macro - * to initialize lock variables when it cannot be insured - * that they can be initialized in a thread safe environment. - * - * NSLock *my_lock = nil; - * - * void function (void) - * { - * [GS_INITIALIZED_LOCK(my_lock, NSRecursiveLock) lock]; - * do_work (); - * [my_lock unlock]; - * } - * - * - */ + (id) newLockAt: (id *)location { return newLockAt(self, _cmd, location); diff --git a/Source/Additions/Unicode.m b/Source/Additions/Unicode.m index 4f7f8b59d..c84abdbec 100644 --- a/Source/Additions/Unicode.m +++ b/Source/Additions/Unicode.m @@ -1134,7 +1134,7 @@ else \ * *

On return, the function result is a flag indicating success (YES) * or failure (NO), and on success, the value stored in size is the number - * of characters in the converted string. The converted string itsself is + * of characters in the converted string. The converted string itself is * stored in the location given by dst.
* NB. If the value stored in dst has been changed, it is a pointer to * allocated memory which the caller is responsible for freeing, and the diff --git a/Source/GSString.m b/Source/GSString.m index a5b942839..d17dbcf59 100644 --- a/Source/GSString.m +++ b/Source/GSString.m @@ -313,7 +313,7 @@ setup(void) * The GSPlaceholderString class is used by the abstract cluster root * class to provide temporary objects that will be replaced as soon * as the objects are initialised. This object tries to replace - * itsself with an appropriate object whose type may vary depending + * itself with an appropriate object whose type may vary depending * on the initialisation method used. */ @implementation GSPlaceholderString diff --git a/Source/GSTcpPort.m b/Source/GSTcpPort.m index b7c563a23..0227ddc0a 100644 --- a/Source/GSTcpPort.m +++ b/Source/GSTcpPort.m @@ -1996,7 +1996,7 @@ static unsigned wordAlign; header = [components objectAtIndex: 0]; /* * The Item header contains the item type and the length of the - * data in the item (excluding the item header itsself). + * data in the item (excluding the item header itself). */ hLength = [header length]; l = hLength - sizeof(GSPortItemHeader); diff --git a/Source/NSArchiver.m b/Source/NSArchiver.m index c011d0f7e..e6ad263c4 100644 --- a/Source/NSArchiver.m +++ b/Source/NSArchiver.m @@ -56,6 +56,16 @@ NSString * const NSInconsistentArchiveException = #define PREFIX "GNUstep archive" +/** + *

Implementation of [NSCoder] capable of creating sequential archives which + * must be read in the same order they were written. This class implements + * methods for saving to and restoring from a serial archive (usually a file + * on disk, but can be an [NSData] object) as well as methods that can be + * used by objects that need to write/restore themselves.

+ * + *

Note, the sibling class [NSKeyedArchiver] supports a form of archive + * that is more robust to class changes, and is recommended over this one.

+ */ @implementation NSArchiver static SEL serSel; @@ -80,6 +90,10 @@ static Class NSMutableDataMallocClass; } } +/** + * Creates an NSMutableData instance and calls + * [initForWritingWithMutableData:]. + */ - (id) init { NSMutableData *d; @@ -90,6 +104,10 @@ static Class NSMutableDataMallocClass; return self; } +/** + * Init instance that will archive its data to mdata. (Even if + * [archiveRootObject:toFile:] is called, this still gets written to.) + */ - (id) initForWritingWithMutableData: (NSMutableData*)mdata { self = [super init]; @@ -164,6 +182,10 @@ static Class NSMutableDataMallocClass; [super dealloc]; } +/** + * Writes serialized representation of object and, recursively, any + * other objects it holds references to, to byte array. + */ + (NSData*) archivedDataWithRootObject: (id)rootObject { NSArchiver *archiver; @@ -197,6 +219,10 @@ static Class NSMutableDataMallocClass; return d; } +/** + * Writes out serialized representation of object and, recursively, any + * other objects it holds references to. + */ + (BOOL) archiveRootObject: (id)rootObject toFile: (NSString*)path { @@ -804,11 +830,19 @@ static Class NSMutableDataMallocClass; } } +/** + * Returns whatever data has been encoded thusfar. + */ - (NSMutableData*) archiverData { return _data; } +/** + * Returns substitute class used to encode objects of given class. This + * would have been set through an earlier call to + * [NSArchiver -encodeClassName:intoClassName:]. + */ - (NSString*) classNameEncodedForTrueClassName: (NSString*)trueName { if (_namMap->nodeCount) @@ -827,6 +861,14 @@ static Class NSMutableDataMallocClass; return trueName; } +/** + * Specify substitute class used in archiving objects of given class. This + * class is written to the archive as the class to use for restoring the + * object, instead of what is returned from [NSObject -classForArchiver]. + * This can be used to provide backward compatibility across class name + * changes. The object is still encoded by calling + * encodeWithCoder: as normal. + */ - (void) encodeClassName: (NSString*)trueName intoClassName: (NSString*)inArchiveName { @@ -857,6 +899,9 @@ static Class NSMutableDataMallocClass; } } +/** + * Set encoder to write out newObject in place of object. + */ - (void) replaceObject: (id)object withObject: (id)newObject { @@ -886,14 +931,15 @@ static Class NSMutableDataMallocClass; -/* - * Catagories for compatibility with old GNUstep encoding. +/** + * Catagory for compatibility with old GNUstep encoding. */ - @implementation NSArchiver (GNUstep) -/* Re-using an archiver */ - +/** + * Allow reuse of archiver (clears class substitution maps, etc.) but + * do not clear out current serialized data. + */ - (void) resetArchiver { if (_clsMap) @@ -937,11 +983,17 @@ static Class NSMutableDataMallocClass; pointers: 0]; } +/** + * Returns YES. + */ - (BOOL) directDataAccess { return YES; } +/** + * Writes out header for GNUstep archive format. + */ - (void) serializeHeaderAt: (unsigned)positionInData version: (unsigned)systemVersion classes: (unsigned)classCount diff --git a/Source/NSArray.m b/Source/NSArray.m index 7f160b31e..1b709bfb0 100644 --- a/Source/NSArray.m +++ b/Source/NSArray.m @@ -643,7 +643,7 @@ static SEL rlSel; * which must contain an array in property-list format. *

*

In GNUstep, the property-list format may be either the OpenStep - * format (ASCII data), or the MacOS-X format (URF8 XML data) ... this + * format (ASCII data), or the MacOS-X format (UTF-8 XML data) ... this * method will recognise which it is. *

*

If there is a failure to load the file for any reason, the receiver @@ -937,8 +937,8 @@ compare(id elem1, id elem2, void* context) /** * Returns an autoreleased array in which the objects are ordered * according to a sort with comparator, where the comparator function - * is passed two objects to compare, and the copntext as the third - * argument. + * is passed two objects to compare, and the context as the third + * argument. The hint argument is currently ignored, and may be nil. */ - (NSArray*) sortedArrayUsingFunction: (NSComparisonResult(*)(id,id,void*))comparator context: (void*)context @@ -1243,6 +1243,10 @@ compare(id elem1, id elem2, void* context) @end +/** + * NSMutableArray is the mutable version of [NSArray]. It + * provides methods for altering the contents of the array. + */ @implementation NSMutableArray + (void) initialize @@ -1412,7 +1416,7 @@ compare(id elem1, id elem2, void* context) } /** - * Removes all occurrances of anObject (found by pointer equality) + * Removes all occurrences of anObject (found by pointer equality) * from the receiver. */ - (void) removeObjectIdenticalTo: (id)anObject @@ -1447,7 +1451,7 @@ compare(id elem1, id elem2, void* context) } /** - * Removes all occurrances of anObject (found by the -isEqual: method + * Removes all occurrences of anObject (found by the -isEqual: method * of anObject) aRange in the receiver. */ - (void) removeObject: (id)anObject inRange: (NSRange)aRange @@ -1547,7 +1551,7 @@ compare(id elem1, id elem2, void* context) } /** - * Removes all occurrances of anObject (found by anObjects -isEqual: method) + * Removes all occurrences of anObject (found by anObjects -isEqual: method) * from the receiver. */ - (void) removeObject: (id)anObject @@ -1928,7 +1932,9 @@ compare(id elem1, id elem2, void* context) } @end - +/** + * [NSArray] enhancements provided by GNUstep. + */ @implementation NSArray (GNUstep) /** diff --git a/Source/NSAttributedString.m b/Source/NSAttributedString.m index 2fa482f4f..2b09c1a0c 100644 --- a/Source/NSAttributedString.m +++ b/Source/NSAttributedString.m @@ -85,7 +85,13 @@ static IMP remDictImp; + (NSMutableString*) stringWithOwner: (NSMutableAttributedString*)as; @end - +/** + * A string in which name-value pairs represented by an [NSDictionary] may + * be associated to ranges of characters. Used for text rendering by the + * GUI/AppKit framework, in which fonts, sizes, etc. are stored under standard + * attributes in the dictionaries. + * + */ @implementation NSAttributedString static Class NSAttributedStringClass; @@ -232,16 +238,26 @@ static Class GSMutableAttributedStringClass; return [self initWithString: nil attributes: nil]; } +/** + * Initialize to aString with no attributes. + */ - (id) initWithString: (NSString*)aString { return [self initWithString: aString attributes: nil]; } +/** + * Initialize to copy of attributedString. + */ - (id) initWithAttributedString: (NSAttributedString*)attributedString { return [self initWithString: (NSString*)attributedString attributes: nil]; } +/** + * Initialize to aString with given attributes applying over full range of + * string. + */ - (id) initWithString: (NSString*)aString attributes: (NSDictionary*)attributes { //This is the designated initializer @@ -269,11 +285,17 @@ static Class GSMutableAttributedStringClass; } //Retrieving character information +/** + * Return length of the underlying string. + */ - (unsigned int) length { return [[self string] length]; } +/** + * Return the underlying string, stripped of attributes. + */ - (NSString*) string { [self subclassResponsibility: _cmd];/* Primitive method! */ @@ -281,6 +303,12 @@ static Class GSMutableAttributedStringClass; } //Retrieving attribute information +/** + * Returns attributes and values at index, and, if effectiveRange + * is non-nil, this gets filled with a range over which these attributes + * and values still hold. This may not be the maximum range, depending + * on the implementation. + */ - (NSDictionary*) attributesAtIndex: (unsigned int)index effectiveRange: (NSRange*)aRange { @@ -288,6 +316,11 @@ static Class GSMutableAttributedStringClass; return nil; } +/** + * Returns attributes and values at index, and, if longestEffectiveRange + * is non-nil, this gets filled with the range over which the attribute-value + * set is the same as at index, clipped to rangeLimit. + */ - (NSDictionary*) attributesAtIndex: (unsigned int)index longestEffectiveRange: (NSRange*)aRange inRange: (NSRange)rangeLimit @@ -337,6 +370,11 @@ static Class GSMutableAttributedStringClass; return attrDictionary; } +/** + * Returns value for given attribute at index, and, if effectiveRange is + * non-nil, this gets filled with a range over which this value holds. This + * may not be the maximum range, depending on the implementation. + */ - (id) attribute: (NSString*)attributeName atIndex: (unsigned int)index effectiveRange: (NSRange*)aRange @@ -362,6 +400,11 @@ static Class GSMutableAttributedStringClass; return attrValue; } +/** + * Returns value for given attribute at index, and, if longestEffectiveRange + * is non-nil, this gets filled with the range over which the attribute + * applies, clipped to rangeLimit. + */ - (id) attribute: (NSString*)attributeName atIndex: (unsigned int)index longestEffectiveRange: (NSRange*)aRange @@ -432,6 +475,10 @@ static Class GSMutableAttributedStringClass; } //Comparing attributed strings +/** + * Returns whether all characters and attributes are equal between this + * string and otherString. + */ - (BOOL) isEqualToAttributedString: (NSAttributedString*)otherString { NSRange ownEffectiveRange,otherEffectiveRange; @@ -492,6 +539,9 @@ static Class GSMutableAttributedStringClass; //Extracting a substring +/** + * Returns substring with attribute information. + */ - (NSAttributedString*) attributedSubstringFromRange: (NSRange)aRange { NSAttributedString *newAttrString; @@ -537,6 +587,9 @@ static Class GSMutableAttributedStringClass; return newAttrString; } +/** + * Synonym for [-attributedSubstringFromRange:]. + */ - (NSAttributedString*) attributedSubstringWithRange: (NSRange)aRange { return [self attributedSubstringFromRange: aRange]; @@ -544,6 +597,9 @@ static Class GSMutableAttributedStringClass; @end //NSAttributedString +/** + * Mutable version of [NSAttributedString]. + */ @implementation NSMutableAttributedString + (id) allocWithZone: (NSZone*)z @@ -601,23 +657,35 @@ static Class GSMutableAttributedStringClass; } //Retrieving character information +/** + * Returns mutable version of the underlying string. + */ - (NSMutableString*) mutableString { return [GSMutableAttributedStringTracker stringWithOwner: self]; } //Changing characters +/** + * Removes characters and attributes applying to them. + */ - (void) deleteCharactersInRange: (NSRange)aRange { [self replaceCharactersInRange: aRange withString: nil]; } //Changing attributes +/** + * Sets attributes to apply over range, replacing any previous attributes. + */ - (void) setAttributes: (NSDictionary*)attributes range: (NSRange)aRange { [self subclassResponsibility: _cmd];// Primitive method! } +/** + * Adds attribute applying to given range. + */ - (void) addAttribute: (NSString*)name value: (id)value range: (NSRange)aRange { NSRange effectiveRange; @@ -664,6 +732,9 @@ static Class GSMutableAttributedStringClass; } } +/** + * Add attributes to apply over given range. + */ - (void) addAttributes: (NSDictionary*)attributes range: (NSRange)aRange { NSRange effectiveRange; @@ -721,6 +792,9 @@ static Class GSMutableAttributedStringClass; } } +/** + * Removes given attribute from aRange. + */ - (void) removeAttribute: (NSString*)name range: (NSRange)aRange { NSRange effectiveRange; @@ -768,12 +842,18 @@ static Class GSMutableAttributedStringClass; } //Changing characters and attributes +/** + * Appends attributed string to end of this one, preserving attributes. + */ - (void) appendAttributedString: (NSAttributedString*)attributedString { [self replaceCharactersInRange: NSMakeRange([self length],0) withAttributedString: attributedString]; } +/** + * Inserts attributed string within this one, preserving attributes. + */ - (void) insertAttributedString: (NSAttributedString*)attributedString atIndex: (unsigned int)index { @@ -781,6 +861,9 @@ static Class GSMutableAttributedStringClass; withAttributedString: attributedString]; } +/** + * Replaces substring and attributes. + */ - (void) replaceCharactersInRange: (NSRange)aRange withAttributedString: (NSAttributedString*)attributedString { @@ -823,12 +906,19 @@ static Class GSMutableAttributedStringClass; [self endEditing]; } +/** + * Replaces substring; replacement is granted attributes equal to those of + * the first character of the portion replaced. + */ - (void) replaceCharactersInRange: (NSRange)aRange withString: (NSString*)aString { [self subclassResponsibility: _cmd];// Primitive method! } +/** + * Replaces entire contents (so this object can be reused). + */ - (void) setAttributedString: (NSAttributedString*)attributedString { [self replaceCharactersInRange: NSMakeRange(0,[self length]) @@ -836,11 +926,17 @@ static Class GSMutableAttributedStringClass; } //Grouping changes +/** + * Call before executing a collection of changes, for optimization. + */ - (void) beginEditing { //Overridden by subclasses } +/** + * Call after executing a collection of changes, for optimization. + */ - (void) endEditing { //Overridden by subclasses diff --git a/Source/NSBitmapCharSet.m b/Source/NSBitmapCharSet.m index 2a12032b8..fa1f3029e 100644 --- a/Source/NSBitmapCharSet.m +++ b/Source/NSBitmapCharSet.m @@ -36,7 +36,7 @@ return [self initWithBitmap: NULL]; } -/* Designated initializer */ +/** Designated initializer */ - (id) initWithBitmap: (NSData*)bitmap { [super init]; diff --git a/Source/NSCalendarDate.m b/Source/NSCalendarDate.m index 17c45b584..927ce0a26 100644 --- a/Source/NSCalendarDate.m +++ b/Source/NSCalendarDate.m @@ -2246,7 +2246,7 @@ static void Grow(DescriptionInfo *info, unsigned size) @end /** - * Routines for manipulating Gregorian dates + * Routines for manipulating Gregorian dates. */ // The following code is based upon the source code in // ``Calendrical Calculations'' by Nachum Dershowitz and Edward M. Reingold, @@ -2288,7 +2288,7 @@ static void Grow(DescriptionInfo *info, unsigned size) /** - * Methods present in OpenStep but later removed from MacOS-X + * Methods present in OpenStep but later removed from MacOS-X. */ @implementation NSCalendarDate (OPENSTEP) diff --git a/Source/NSCharacterSet.m b/Source/NSCharacterSet.m index 781a677c1..01eff3a98 100644 --- a/Source/NSCharacterSet.m +++ b/Source/NSCharacterSet.m @@ -45,6 +45,10 @@ static NSCharacterSet *cache_set[MAX_STANDARD_SETS]; static NSLock *cache_lock = nil; static Class abstractClass = nil; +/** + * Represents a set of unicode characters. Used by [NSScanner] and [NSString] + * for parsing-related methods. + */ @implementation NSCharacterSet + (void) initialize @@ -139,11 +143,19 @@ static Class abstractClass = nil; } +/** + * Returns a character set containing letters, numbers, and diacritical + * marks. Note that "letters" includes all alphabetic as well as Chinese + * characters, etc.. + */ + (NSCharacterSet*) alphanumericCharacterSet { return [self _bitmapForSet: @"alphanumericCharSet" number: 0]; } +/** + * Returns a character set containing control and format characters. + */ + (NSCharacterSet*) controlCharacterSet { return [self _bitmapForSet: @"controlCharSet" number: 1]; @@ -176,6 +188,10 @@ static Class abstractClass = nil; return [self _bitmapForSet: @"illegalCharSet" number: 4]; } +/** + * Returns a character set containing letters, including all alphabetic as + * well as Chinese characters, etc.. + */ + (NSCharacterSet*) letterCharacterSet { return [self _bitmapForSet: @"letterCharSet" number: 5]; @@ -191,16 +207,26 @@ static Class abstractClass = nil; return [self _bitmapForSet: @"lowercaseLetterCharSet" number: 6]; } +/** + * Returns a character set containing characters for diacritical marks, which + * are usually only rendered in conjunction with another character. + */ + (NSCharacterSet*) nonBaseCharacterSet { return [self _bitmapForSet: @"nonBaseCharSet" number: 7]; } +/** + * Returns a character set containing punctuation marks. + */ + (NSCharacterSet*) punctuationCharacterSet { return [self _bitmapForSet: @"punctuationCharSet" number: 8]; } +/** + * Returns a character set containing mathematical symbols, etc.. + */ + (NSCharacterSet*) symbolAndOperatorCharacterSet { return [self _bitmapForSet: @"symbolAndOperatorCharSet" number: 9]; @@ -244,6 +270,10 @@ static Class abstractClass = nil; return AUTORELEASE([[NSBitmapCharSet alloc] initWithBitmap: data]); } +/** + * Returns set with characters in aString, or empty set for empty string. + * Raises an exception if given a nil string. + */ + (NSCharacterSet*) characterSetWithCharactersInString: (NSString*)aString { unsigned i; @@ -270,6 +300,9 @@ static Class abstractClass = nil; return [self characterSetWithBitmapRepresentation: bitmap]; } +/** + * Returns set containing unicode index range given by aRange. + */ + (NSCharacterSet*)characterSetWithRange: (NSRange)aRange { unsigned i; @@ -291,6 +324,12 @@ static Class abstractClass = nil; return [self characterSetWithBitmapRepresentation: bitmap]; } +/** + * Initializes from a bitmap. (See [NSBitmapCharSet].) File must have + * extension ".bitmap". (To get around this load the file + * into data yourself and use + * [NSCharacterSet -characterSetWithBitmapRepresentation]. + */ + (NSCharacterSet*) characterSetWithContentsOfFile: (NSString*)aFile { if ([@"bitmap" isEqual: [aFile pathExtension]]) @@ -394,6 +433,9 @@ static Class abstractClass = nil; @end +/** + * An [NSCharacterSet] that can be modified. + */ @implementation NSMutableCharacterSet /* Provide a default object for allocation */ @@ -408,37 +450,61 @@ static Class abstractClass = nil; return AUTORELEASE([[NSMutableBitmapCharSet alloc] initWithBitmap: data]); } -/* Mutable subclasses must implement ALL of these methods. */ +/* Mutable subclasses must implement ALL of these methods. */ + +/** + * Adds characters specified by unicode indices in aRange to set. + */ - (void) addCharactersInRange: (NSRange)aRange { [self subclassResponsibility: _cmd]; } +/** + * Adds characters in aString to set. + */ - (void) addCharactersInString: (NSString*)aString { [self subclassResponsibility: _cmd]; } +/** + * Set union of character sets. + */ - (void) formUnionWithCharacterSet: (NSCharacterSet*)otherSet { [self subclassResponsibility: _cmd]; } +/** + * Set intersection of character sets. + */ - (void) formIntersectionWithCharacterSet: (NSCharacterSet*)otherSet { [self subclassResponsibility: _cmd]; } +/** + * Drop given range of characters. No error for characters not currently in + * set. + */ - (void) removeCharactersInRange: (NSRange)aRange { [self subclassResponsibility: _cmd]; } +/** + * Drop characters in aString. No error for characters not currently in + * set. + */ - (void) removeCharactersInString: (NSString*)aString { [self subclassResponsibility: _cmd]; } +/** + * Remove all characters currently in set and add all other characters. + */ - (void) invert { [self subclassResponsibility: _cmd]; diff --git a/Source/NSClassDescription.m b/Source/NSClassDescription.m index ef81306c7..efe717f34 100644 --- a/Source/NSClassDescription.m +++ b/Source/NSClassDescription.m @@ -30,19 +30,28 @@ #include "Foundation/NSNotification.h" +/** + * Each instance of this class provides descriptive information for an + * Objective C class. This is used for key-value coding, a framework + * used in Cocoa for scripting with Objective-C objects. Scripting is + * available in GNUstep using Guile, however that implementation does + * not make use of class descriptions. Therefore the primary purpose + * of this class is to smooth the process of porting between GNUstep + * and other OpenStep-derived systems. + */ @implementation NSClassDescription static NSRecursiveLock *mapLock = nil; static NSMapTable *classMap; /** - * Returns the class descriptuion for aClass. If there is no such description - * available, sends an NSClassDescriptionNeededForClassNotification (with - * aClass as its object) so that objects providing class descriptions can - * register one, and tries again to find one.
- * Returns nil if there is no description found.
- * Handles locking to ensure thread safety and ensures that the returned - * object will not be destroyed by other threads. + * Returns the class description for aClass. If there is no such description + * available, sends an + * NSClassDescriptionNeededForClassNotification (with aClass as + * its object) so that objects providing class descriptions can register one, + * and tries again to find one.
Returns nil if there is no description + * found.
Handles locking to ensure thread safety and ensures that the + * returned object will not be destroyed by other threads. */ + (NSClassDescription*) classDescriptionForClass: (Class)aClass { diff --git a/Source/NSCoder.m b/Source/NSCoder.m index 2610164b4..9a882c739 100644 --- a/Source/NSCoder.m +++ b/Source/NSCoder.m @@ -290,6 +290,8 @@ - (unsigned int) systemVersion { + //PENDING(ABR)- should probably mult major version by 1000, not 100, since, + // e.g., 2.0.0 is going to be <1000 return (((GNUSTEP_BASE_MAJOR_VERSION * 100) + GNUSTEP_BASE_MINOR_VERSION) * 100) + GNUSTEP_BASE_SUBMINOR_VERSION; } diff --git a/Source/NSCountedSet.m b/Source/NSCountedSet.m index 7eec11872..bfdf00752 100644 --- a/Source/NSCountedSet.m +++ b/Source/NSCountedSet.m @@ -50,13 +50,14 @@ static BOOL uniquing = NO; /** *

- * The NSCountedSet class is used to maintain a set of objects where - * the number of times each object has been added (wiithout a + * The NSCountedSet class is used to maintain a set of objects + * where the number of times each object has been added (without a * corresponding removal) is kept track of. *

*

- * In GNUstep, extra methods are provided to make use of a counted - * set for uniquing objects easier. + * In GNUstep, the purge and unique methods + * are provided to make use of a counted set for uniquing objects + * easier. *

*/ @implementation NSCountedSet @@ -90,7 +91,7 @@ static Class NSCountedSet_concrete_class; /** * Returns the number of times that an object that is equal to the - * specified object (as determined byt the [-isEqual:] method) has + * specified object (as determined by the [-isEqual:] method) has * been added to the set and not removed from it. */ - (unsigned int) countForObject: (id)anObject @@ -205,17 +206,6 @@ static Class NSCountedSet_concrete_class; return self; } -/** - *

- * This method removes from the set all objects whose count is - * less than or equal to the specified value. - *

- *

- * This is useful where a counted set is used for uniquing objects. - * The set can be periodically purged of objects that have only - * been added once - and are therefore simply wasting space. - *

- */ - (void) purge: (int)level { if (level > 0) @@ -251,22 +241,6 @@ static Class NSCountedSet_concrete_class; } } -/** - *

- * If the supplied object (or one equal to it as determined by - * the [-isEqual:] method) is already present in the set, the - * count for that object is incremented, the supplied object - * is released, and the object in the set is retained and returned. - * Otherwise, the supplied object is added to the set and returned. - *

- *

- * This method is useful for uniquing objects - the init method of - * a class need simply end with - - * - * return [myUniquingSet unique: self]; - * - *

- */ - (id) unique: (id)anObject { id o = [self member: anObject]; @@ -288,7 +262,7 @@ static Class NSCountedSet_concrete_class; @end /** - * This function purges the global NSCountedSet object used for + * This function purges the global [NSCountedSet] object used for * uniquing. It handles locking as necessary. It can be used to * purge the set even when uniquing is turned off. */ diff --git a/Source/NSData.m b/Source/NSData.m index 898173942..f1f4e6710 100644 --- a/Source/NSData.m +++ b/Source/NSData.m @@ -310,6 +310,17 @@ failure: #endif + +/** + *

Class for storing a byte array. Methods for initializing from memory a + * file, or the network are provided, as well as the ability to write to a + * file or the network. If desired, object can take over management of a + * pre-allocated buffer (with malloc or similar), free'ing it when deallocated. + *

+ *

The data buffer at any given time has a capacity, which is the + * size of its allocated memory area, in bytes, and a length, which + * is the length of data it is currently storing.

+ */ @implementation NSData #if NEED_WORD_ALIGNMENT @@ -574,6 +585,11 @@ static unsigned gsu32Align; return self; } +/** + * Initialize with data pointing to contents of file at path. Bytes are + * only "swapped in" as needed. File should not be moved or deleted for + * the life of this object. + */ - (id) initWithContentsOfMappedFile: (NSString *)path { #ifdef HAVE_MMAP @@ -586,6 +602,10 @@ static unsigned gsu32Align; #endif } +/** + * Initialize with data pointing to contents of URL, which will be + * retrieved immediately in a blocking manner. + */ - (id) initWithContentsOfURL: (NSURL*)url { NSData *data = [url resourceDataUsingCache: YES]; @@ -593,6 +613,9 @@ static unsigned gsu32Align; return [self initWithData: data]; } +/** + * Initializes by copying data's bytes into a new buffer. + */ - (id) initWithData: (NSData*)data { if (data == nil) @@ -620,6 +643,9 @@ static unsigned gsu32Align; return NULL; } +/** + * Returns a short description of this object. + */ - (NSString*) description { extern void GSPropertyListMake(id,NSDictionary*,BOOL,BOOL,unsigned,id*); @@ -987,11 +1013,19 @@ failure: // Deserializing Data +/** + * Copies data from buffer starting from cursor. Deprecated. + * Use [-getBytes:] and related methods instead. + */ - (unsigned int) deserializeAlignedBytesLengthAtCursor: (unsigned int*)cursor { return (unsigned)[self deserializeIntAtCursor: cursor]; } +/** + * Copies data from buffer starting from cursor. Deprecated. + * Use [-getBytes:] and related methods instead. + */ - (void) deserializeBytes: (void*)buffer length: (unsigned int)bytes atCursor: (unsigned int*)cursor @@ -1289,6 +1323,10 @@ failure: } } +/** + * Retrieve an int from this data, which is assumed to be in network + * (big-endian) byte order. Cursor refers to byte position. + */ - (int) deserializeIntAtCursor: (unsigned int*)cursor { unsigned ni, result; @@ -1298,6 +1336,10 @@ failure: return result; } +/** + * Retrieve an int from this data, which is assumed to be in network + * (big-endian) byte order. Index refers to byte position. + */ - (int) deserializeIntAtIndex: (unsigned int)index { unsigned ni, result; @@ -1307,6 +1349,11 @@ failure: return result; } +/** + * Retrieve ints from intBuffer, which is assumed to be in network (big-endian) + * byte order. Count refers to number of ints, but index refers to byte + * position. + */ - (void) deserializeInts: (int*)intBuffer count: (unsigned int)numInts atCursor: (unsigned int*)cursor @@ -1320,6 +1367,11 @@ failure: intBuffer[i] = NSSwapBigIntToHost(intBuffer[i]); } +/** + * Retrieve ints from intBuffer, which is assumed to be in network (big-endian) + * byte order. Count refers to number of ints, but index refers to byte + * position. + */ - (void) deserializeInts: (int*)intBuffer count: (unsigned int)numInts atIndex: (unsigned int)index @@ -1369,7 +1421,14 @@ failure: @end +/** + * Provides some shared-memory extensions to [NSData]. + */ @implementation NSData (GNUstepExtensions) + +/** + * New instance with given shared memory ID. + */ + (id) dataWithShmID: (int)anID length: (unsigned int)length { #ifdef HAVE_SHMCTL @@ -1384,6 +1443,9 @@ failure: #endif } +/** + * New instance with given bytes in shared memory. + */ + (id) dataWithSharedBytes: (const void*)bytes length: (unsigned int)length { NSData *d; @@ -1463,6 +1525,10 @@ failure: @end +/** + * Mutable version of [NSData]. Methods are provided for appending and + * replacing bytes in the buffer, which will be grown as needed. + */ @implementation NSMutableData + (id) allocWithZone: (NSZone*)z { @@ -1505,6 +1571,10 @@ failure: return AUTORELEASE(d); } +/** + * New instance with buffer of given numBytes with length of valid data set + * to zero. Note that capacity will be automatically increased as necessary. + */ + (id) dataWithCapacity: (unsigned int)numBytes { NSMutableData *d; @@ -1552,6 +1622,12 @@ failure: return AUTORELEASE(d); } +/** + * New instance with buffer of capacity and valid data size equal to given + * length in bytes. The buffer contents are set to zero. The length of + * valid data is set to zero. Note that buffer will be automatically + * increased as necessary. + */ + (id) dataWithLength: (unsigned int)length { NSMutableData *d; @@ -1590,6 +1666,11 @@ failure: } } +/** + * Initialize with buffer capable of holding size bytes. The length of valid + * data is initially set to zero. + * + */ - (id) initWithCapacity: (unsigned int)capacity { [self subclassResponsibility: _cmd]; @@ -1628,6 +1709,10 @@ failure: return self; } +/** + * Initialize with buffer of capacity equal to length, and with the length + * of valid data set to length. Data is set to zero. + */ - (id) initWithLength: (unsigned int)length { [self subclassResponsibility: _cmd]; @@ -1635,7 +1720,10 @@ failure: } // Adjusting Capacity - +/** + * Increases buffer length by given number of bytes, filling the new space + * with zeros. + */ - (void) increaseLengthBy: (unsigned int)extraLength { [self setLength: [self length]+extraLength]; @@ -1683,6 +1771,10 @@ failure: // Appending Data +/** + * Appends bufferSize bytes from aBuffer to data, increasing capacity if + * necessary. + */ - (void) appendBytes: (const void*)aBuffer length: (unsigned int)bufferSize { @@ -1694,6 +1786,10 @@ failure: memcpy(buffer + oldLength, aBuffer, bufferSize); } +/** + * Copies and appends data from other to data, increasing capacity if + * necessary. + */ - (void) appendData: (NSData*)other { [self appendBytes: [other bytes] length: [other length]]; @@ -1784,6 +1880,9 @@ failure: } } +/** + * Set bytes in aRange to 0. + */ - (void) resetBytesInRange: (NSRange)aRange { unsigned size = [self length]; @@ -1792,6 +1891,10 @@ failure: memset((char*)[self bytes] + aRange.location, 0, aRange.length); } +/** + * Replaces contents of buffer with contents of data's buffer, increasing + * or shrinking capacity to match. + */ - (void) setData: (NSData*)data { NSRange r = NSMakeRange(0, [data length]); @@ -1802,6 +1905,10 @@ failure: // Serializing Data +/** + * Does not act as the name suggests. Instead, serializes length itself + * as an int into buffer. + */ - (void) serializeAlignedBytesLength: (unsigned int)length { [self serializeInt: length]; @@ -1976,12 +2083,21 @@ failure: } } +/** + * Serialize an int into this object's data buffer, swapping it to network + * (big-endian) byte order first. + */ - (void) serializeInt: (int)value { unsigned ni = NSSwapHostIntToBig(value); [self appendBytes: &ni length: sizeof(unsigned)]; } +/** + * Serialize an int into this object's data buffer at index (replacing + * anything there currently), swapping it to network (big-endian) byte order + * first. + */ - (void) serializeInt: (int)value atIndex: (unsigned int)index { unsigned ni = NSSwapHostIntToBig(value); @@ -1990,6 +2106,10 @@ failure: [self replaceBytesInRange: range withBytes: &ni]; } +/** + * Serialize one or more ints into this object's data buffer, swapping them to + * network (big-endian) byte order first. + */ - (void) serializeInts: (int*)intBuffer count: (unsigned int)numInts { @@ -2003,6 +2123,11 @@ failure: } } +/** + * Serialize one or more ints into this object's data buffer at index + * (replacing anything there currently), swapping them to network (big-endian) + * byte order first. + */ - (void) serializeInts: (int*)intBuffer count: (unsigned int)numInts atIndex: (unsigned int)index @@ -2019,7 +2144,15 @@ failure: @end + +/** + * Provides some additional methods to [NSData]. + */ @implementation NSMutableData (GNUstepExtensions) + +/** + * New instance with given shared memory ID. + */ + (id) dataWithShmID: (int)anID length: (unsigned int)length { #ifdef HAVE_SHMCTL @@ -2034,6 +2167,9 @@ failure: #endif } +/** + * New instance with given bytes in shared memory. + */ + (id) dataWithSharedBytes: (const void*)bytes length: (unsigned int)length { NSData *d; @@ -2048,18 +2184,28 @@ failure: return AUTORELEASE(d); } +/** + * Returns current capacity of data buffer. + */ - (unsigned int) capacity { [self subclassResponsibility: _cmd]; return 0; } +/** + * Sets current capacity of data buffer. Unlike [-setLength:], this will + * shrink the buffer if requested. + */ - (id) setCapacity: (unsigned int)newCapacity { [self subclassResponsibility: _cmd]; return nil; } +/** + * Return shared memory ID, if using one, else -1. + */ - (int) shmID { return -1; @@ -2614,6 +2760,11 @@ getBytes(void* dst, void* src, unsigned len, unsigned limit, unsigned *pos) [super dealloc]; } +/** + * Initialize with data pointing to contents of file at path. Bytes are + * only "swapped in" as needed. File should not be moved or deleted for + * the life of this object. + */ - (id) initWithContentsOfMappedFile: (NSString*)path { int fd; @@ -2858,8 +3009,10 @@ getBytes(void* dst, void* src, unsigned len, unsigned limit, unsigned *pos) return self; } -/* - * THIS IS THE DESIGNATED INITIALISER +// THIS IS THE DESIGNATED INITIALISER +/** + * Initialize with buffer capable of holding size bytes. + * */ - (id) initWithCapacity: (unsigned int)size { @@ -2890,6 +3043,10 @@ getBytes(void* dst, void* src, unsigned len, unsigned limit, unsigned *pos) return self; } +/** + * Initialize with buffer capable of holding size bytes. Buffer is zeroed + * out. + */ - (id) initWithLength: (unsigned int)size { self = [self initWithCapacity: size]; diff --git a/Source/NSDate.m b/Source/NSDate.m index 17d2b19d8..0a902c7b6 100644 --- a/Source/NSDate.m +++ b/Source/NSDate.m @@ -168,9 +168,12 @@ GSTimeNow(void) } /** - * NSDate is the abstract base class of a cluster of date classes.
- * An NSDate object encapsulates a constant date/time to a high - * resolution represented by the NSTimeInterval typedef. + * An NSDate object encapsulates a constant date/time to a high + * resolution represented by the NSTimeInterval typedef. + * NSDate has methods relating to times and time differences in + * the abstract, but not calendar dates or time zones. These features are + * added in the [NSCalendarDate] subclass. The [NSTimeZone] class handles time + * zone information. */ @implementation NSDate @@ -1338,6 +1341,9 @@ GSTimeNow(void) return NO; } +/** + * Returns whether equal to other within one NSTimeInterval unit. + */ - (BOOL) isEqualToDate: (NSDate*)other { if (other == nil) diff --git a/Source/NSDecimal.m b/Source/NSDecimal.m index e086356f6..09fd38659 100644 --- a/Source/NSDecimal.m +++ b/Source/NSDecimal.m @@ -37,7 +37,7 @@ /* This file provides two implementations of the NSDecimal functions. One is based on pure simple decimal mathematics, as we all learned it - in school. This version is rather slow and may be inexact in the extrem + in school. This version is rather slow and may be inexact in the extreme cases. THIS IS TESTED AND WORKING. @@ -48,7 +48,7 @@ The data structure used for NSDecimals is a bit strange. It also does not correspond to the description in the OpenStep specification. But this is - not consistent, so a decission had to be made. + not consistent, so a decision had to be made. The mantissa part (I know D. Knuth does not like this term, but it is used in the specification so we stay with it) consists of up to 38 digits, this are stored as an integer (in decimal representation or limps depending on the @@ -72,7 +72,7 @@ typedef struct { BOOL isNegative; /* Is this negative? */ BOOL validNumber; /* Is this a valid number? */ unsigned char length; /* digits in mantissa. */ - unsigned char cMantissa[2*NSDecimalMaxDigit]; /* Make this big enought for multiplication */ + unsigned char cMantissa[2*NSDecimalMaxDigit]; /* Make this big enough for multiplication */ } GSDecimal; static NSDecimal zero = {0, NO, YES, 0, {0}}; @@ -84,6 +84,15 @@ static NSDecimal one = {0, NO, YES, 1, {1}}; #else // Make GSDecimal a synonym of NSDecimal +/** +typedef struct {
+ signed char exponent; // Signed exponent - -128 to 127
+ BOOL isNegative; // Is this negative?
+ BOOL validNumber; // Is this a valid number?
+ unsigned char length; // digits in mantissa.
+ unsigned char cMantissa[2*NSDecimalMaxDigit];
+}
+ */ typedef NSDecimal GSDecimal; static NSDecimal zero = {0, NO, YES, 0, {0}}; diff --git a/Source/NSDecimalNumber.m b/Source/NSDecimalNumber.m index 54d9adfc1..9284d8ff9 100644 --- a/Source/NSDecimalNumber.m +++ b/Source/NSDecimalNumber.m @@ -30,6 +30,7 @@ #include "Foundation/NSDecimalNumber.h" #include "GSPrivate.h" +// shared default behavior for NSDecimalNumber class static NSDecimalNumberHandler *handler; @implementation NSDecimalNumberHandler diff --git a/Source/NSDictionary.m b/Source/NSDictionary.m index e9c5b557e..954f40a3d 100644 --- a/Source/NSDictionary.m +++ b/Source/NSDictionary.m @@ -43,6 +43,27 @@ #include "GNUstepBase/GSCategories.h" #include "GSPrivate.h" +/** + *

This class and its subclasses store key-value pairs, where the key and + * the value are objects. A great many utility methods for working with + * dictionaries are provided as part of this class, including the ability to + * retrieve multiple entries simultaneously, obtain sorted contents, and + * read/write from/to a serialized representation.

+ * + *

Both keys and values are retained by the implementation, and released + * when either their entry is dropped or the entire dictionary is deallocated. + * This differs from the implementation on OS X, where keys are copied instead + * of being retained and must therefore implement the [NSCopying] protocol.

+ * + *

Objects of this class are immutable. For a mutable version, use the + * [NSMutableDictionary] subclass.

+ * + *

The basic functionality in NSDictionary is similar to that + * in Java's HashMap, and like that class it includes no locking + * code and is not thread-safe. If the contents will be modified and + * accessed from multiple threads you should enclose critical operations + * within locks (see [NSLock]).

+ */ @implementation NSDictionary @class GSDictionary; @@ -96,7 +117,12 @@ static SEL appSel; } } -/** +/** + * Initializes contents to the given objects and keys. + * The two arrays must have the same size. + * The n th element of the objects array is associated with the n th + * element of the keys array. + * */ - (id) initWithObjects: (id*)objects forKeys: (id*)keys @@ -304,6 +330,9 @@ static SEL appSel; return self; } +/** + * Returns a new autoreleased empty dictionary. + */ + (id) dictionary { return AUTORELEASE([[self allocWithZone: NSDefaultMallocZone()] init]); @@ -394,6 +423,12 @@ static SEL appSel; return AUTORELEASE(o); } +/** + * Returns a dictionary created using the given objects and keys. + * The two arrays must have the same length. + * The n th element of the objects array is associated with the n th + * element of the keys array. + */ + (id) dictionaryWithObjects: (NSArray*)objects forKeys: (NSArray*)keys { return AUTORELEASE([[self allocWithZone: NSDefaultMallocZone()] @@ -416,6 +451,10 @@ static SEL appSel; return [self initWithObjects: NULL forKeys: NULL count: 0]; } +/** + * Initializes with the keys and objects of otherDictionary. + * (The keys and objects are not copied.) + */ - (id) initWithDictionary: (NSDictionary*)otherDictionary { return [self initWithDictionary: otherDictionary copyItems: NO]; @@ -478,7 +517,7 @@ static SEL appSel; * which must contain a dictionary in property-list format. *

*

In GNUstep, the property-list format may be either the OpenStep - * format (ASCII data), or the MacOS-X format (URF8 XML data) ... this + * format (ASCII data), or the MacOS-X format (UTF-8 XML data) ... this * method will recognise which it is. *

*

If there is a failure to load the file for any reason, the receiver @@ -531,7 +570,7 @@ static SEL appSel; * which must contain a dictionary in property-list format. *

*

In GNUstep, the property-list format may be either the OpenStep - * format (ASCII data), or the MacOS-X format (URF8 XML data) ... this + * format (ASCII data), or the MacOS-X format (UTF-8 XML data) ... this * method will recognise which it is. *

*

If there is a failure to load the URL for any reason, the receiver @@ -610,6 +649,12 @@ static SEL appSel; return NO; } +/** + * Two dictionaries are equal if they each hold the same number of + * entries, each key in one isEqual to a key in the other, + * and, for a given key, the corresponding value objects also satisfy + * isEqual. + */ - (BOOL) isEqualToDictionary: (NSDictionary*)other { unsigned count; @@ -764,6 +809,14 @@ compareIt(id o1, id o2, void* context) return (int)[o1 performSelector: f->s withObject: o2]; } +/** + * Returns ordered array of the keys sorted according to the values they + * correspond to. To sort the values, a message with selector comp is + * send to each value with another value as argument, as in + * [a comp: b]. The comp method should return + * NSOrderedSame, NSOrderedAscending, or + * NSOrderedDescending as appropriate. + */ - (NSArray*) keysSortedByValueUsingSelector: (SEL)comp { struct foo info; @@ -776,6 +829,12 @@ compareIt(id o1, id o2, void* context) return k; } +/** + * Multiple version of [-objectForKey:]. Objects for each key in keys are + * looked up and placed into return array in same order. For each key that + * has no corresponding value in this dictionary, marker is put into the + * array in its place. + */ - (NSArray*) objectsForKeys: (NSArray*)keys notFoundMarker: (id)marker { unsigned c = [keys count]; @@ -978,6 +1037,10 @@ compareIt(id o1, id o2, void* context) } @end + +/** + * Mutable version of [NSDictionary]. + */ @implementation NSMutableDictionary + (void) initialize @@ -1037,23 +1100,46 @@ compareIt(id o1, id o2, void* context) return NSMutableDictionaryClass; } -/* This is the designated initializer */ +/** + * Initializes an empty dictionary with memory preallocated for given number + * of entries. Although memory space will be grown as needed when entries + * are added, this can avoid the reallocate-and-copy process if the size of + * the ultimate contents is known in advance. + * + */ - (id) initWithCapacity: (unsigned)numItems { [self subclassResponsibility: _cmd]; return 0; } +/** + * Adds entry for aKey, mapping to anObject. If either is nil, an exception + * is raised. If aKey already in dictionary, the value it maps to is + * silently replaced. aKey and anObject are both retained. (This differs + * from OS X, where the key is copied and must therefore implement the + * [NSCopying] protocol.) + */ - (void) setObject: anObject forKey: (id)aKey { [self subclassResponsibility: _cmd]; } +/** + * Remove key-value mapping for given key aKey. No error if there is no + * mapping for the key. A warning will be generated if aKey is nil. + */ - (void) removeObjectForKey: (id)aKey { [self subclassResponsibility: _cmd]; } +/** + * Returns an empty dictionary with memory preallocated for given number of + * entries. Although memory space will be grown as needed when entries are + * added, this can avoid the reallocate-and-copy process if the size of the + * ultimate contents is known in advance. + */ + (id) dictionaryWithCapacity: (unsigned)numItems { return AUTORELEASE([[self allocWithZone: NSDefaultMallocZone()] @@ -1061,6 +1147,12 @@ compareIt(id o1, id o2, void* context) } /* Override superclass's designated initializer */ +/** + * Initializes contents to the given objects and keys. + * The two arrays must have the same size. + * The n th element of the objects array is associated with the n th + * element of the keys array. + */ - (id) initWithObjects: (id*)objects forKeys: (id*)keys count: (unsigned)count @@ -1079,6 +1171,9 @@ compareIt(id o1, id o2, void* context) return self; } +/** + * Clears out this dictionary by removing all entries. + */ - (void) removeAllObjects { id k; @@ -1092,6 +1187,11 @@ compareIt(id o1, id o2, void* context) } } +/** + * Remove entries specified by the given keyArray. No error is generated if + * no mapping exists for a key or one is nil, although a console warning is + * produced in the latter case. + */ - (void) removeObjectsForKeys: (NSArray*)keyArray { unsigned c = [keyArray count]; @@ -1132,6 +1232,9 @@ compareIt(id o1, id o2, void* context) } } +/** + * Remove all entries, then add all entries from otherDictionary. + */ - (void) setDictionary: (NSDictionary*)otherDictionary { [self removeAllObjects]; diff --git a/Source/NSDistantObject.m b/Source/NSDistantObject.m index a006d2ee1..4540009c2 100644 --- a/Source/NSDistantObject.m +++ b/Source/NSDistantObject.m @@ -803,6 +803,9 @@ enum @end +/** + * Adds some backwards-compatibility and other methods. + */ @implementation NSDistantObject(GNUstepExtensions) /** diff --git a/Source/NSDistributedLock.m b/Source/NSDistributedLock.m index f74b8e5e3..f2fc98ecc 100644 --- a/Source/NSDistributedLock.m +++ b/Source/NSDistributedLock.m @@ -36,6 +36,11 @@ static NSFileManager *mgr = nil; +/** + * This class does not adopt the [NSLocking] protocol but supports locking + * across processes, including processes on different machines, as long as + * they can access a common filesystem. + */ @implementation NSDistributedLock + (void) initialize diff --git a/Source/NSDistributedNotificationCenter.m b/Source/NSDistributedNotificationCenter.m index 95c6114f9..f2529fce2 100644 --- a/Source/NSDistributedNotificationCenter.m +++ b/Source/NSDistributedNotificationCenter.m @@ -62,9 +62,9 @@ NSString *GSNetworkNotificationCenterType = @end /** - *

The NSDistributedNotificationCenter provides a versatile yet + *

The NSDistributedNotificationCenter provides a versatile yet * simple mechanism for objects in different processes to communicate - * effectively while knowing very little about each others internals.
+ * effectively while knowing very little about each others' internals.
* A distributed notification center acts much like a normal * notification center, but it handles notifications on a machine-wide * (or local network wide) basis rather than just notifications within @@ -76,7 +76,7 @@ NSString *GSNetworkNotificationCenterType = *

Since posting of distributed notifications involves inter-process * (and sometimes inter-host) communication, it is fundamentally slower * than normal notifications, and should be used relatively sparingly. - * In order to help with this, the NSDistributedNotificationCenter + * In order to help with this, the NSDistributedNotificationCenter * provides a notion of 'suspension', whereby a center can be suspended * causing notifications for observers in the process where the center * was suspended to cease receiving notifications. Observers can @@ -86,19 +86,19 @@ NSString *GSNetworkNotificationCenterType = *

*

Distributed notifications are mediated by a server process which * handles all notifications for a particular center type. In GNUstep - * this process is the gdnc tool, and when started without special + * this process is the gdnc tool, and when started without special * options, a gdnc process acts as the local centre for the host it is - * running on. When started with the GSNetwork user default set to YES, - * the gdnc tool acts as a local network wide server (you should only - * run one copy of gdnc like this on your LAN).
- * The gdnc process should be started at machine boot time, but GNUstep - * will attempt to start it automatically if it can't find it. + * running on. When started with the GSNetwork user default set + * to YES, the gdnc tool acts as a local network wide server (you + * should only run one copy of gdnc like this on your LAN).
+ * The gdnc process should be started at machine boot time, but + * GNUstep will attempt to start it automatically if it can't find it. *

*

MacOS-X currently defines only a notification center for the * local host. GNUstep also defines a local network center which can * be used from multiple hosts. By default the system sends this to * any gdnc process it can find which is configured as a network-wide - * server, but the GDNCHost user default may be used to specify a + * server, but the GDNCHost user default may be used to specify a * particular host to be contacted ... this may be of use where you * wish to have logically separate clusters of machines on a shared LAN. *

@@ -119,7 +119,7 @@ static NSDistributedNotificationCenter *netCenter = nil; * Returns the default notification center ... a shared notification * center for the local host. This is simply a convenience method * equivalent to calling +notificationCenterForType: with - * NSLocalNotificationCenterType as its argument. + * NSLocalNotificationCenterType as its argument. */ + (id) defaultCenter { @@ -128,11 +128,11 @@ static NSDistributedNotificationCenter *netCenter = nil; /** * Returns a notification center of the specified type.
- * The NSLocalNotificationCenterType provides a shared access to + * The NSLocalNotificationCenterType provides a shared access to * a notificatiuon center used by processes on the local host.
- * The GSNetworkNotificationCenterType provides a shared access to + * The GSNetworkNotificationCenterType provides a shared access to * a notificatiuon center used by processes on the local network.
- * MacOS-X supports only NSLocalNotificationCenterType. + * MacOS-X supports only NSLocalNotificationCenterType. */ + (id) notificationCenterForType: (NSString*)type { @@ -225,7 +225,7 @@ static NSDistributedNotificationCenter *netCenter = nil; /** * Adds an observer to the receiver. Calls * -addObserver:selector:name:object:suspensionBehavior: with - * NSNotificationSuspensionBehaviorCoalesce. + * NSNotificationSuspensionBehaviorCoalesce. */ - (void) addObserver: (id)anObserver selector: (SEL)aSelector @@ -248,23 +248,23 @@ static NSDistributedNotificationCenter *netCenter = nil; * when the process to which the notification should be delivered is * suspended: * - * NSNotificationSuspensionBehaviorDrop + * NSNotificationSuspensionBehaviorDrop * * Discards the notification if the observing process is suspended. * - * NSNotificationSuspensionBehaviorCoalesce + * NSNotificationSuspensionBehaviorCoalesce * * Discards previously queued notifications when the observing process * is suspended, leaving only the last notification posted in the queue. * Delivers this single notification when the process becomes unsuspended. * - * NSNotificationSuspensionBehaviorHold + * NSNotificationSuspensionBehaviorHold * * Queues notifications when the observing process is suspended, * delivering all the queued notifications when the process becomes * unsuspended again. * - * NSNotificationSuspensionBehaviorDeliverImmediately + * NSNotificationSuspensionBehaviorDeliverImmediately * * Deliver the notification immediately, even if the destination * process is suspended. @@ -547,7 +547,7 @@ static NSDistributedNotificationCenter *netCenter = nil; /** * Establish a connection to the server. This method should only be called - * when protected by the centres lock, so that it is thread-safe. + * when protected by the center's lock, so that it is thread-safe. */ - (void) _connect { @@ -577,7 +577,7 @@ static NSDistributedNotificationCenter *netCenter = nil; * If we have a host specified, but it is the current host, * we do not need to ask for a host by name (nameserver lookup * can be faster) and the empty host name can be used to - * indicate that we may start a gdnc server locally. + * indicate that we may start a gdnc server locally. */ h = [NSHost hostWithName: host]; if (h == nil) diff --git a/Source/NSEnumerator.m b/Source/NSEnumerator.m index 82d0bd541..aebdfd80d 100644 --- a/Source/NSEnumerator.m +++ b/Source/NSEnumerator.m @@ -29,8 +29,15 @@ #include "Foundation/NSUtilities.h" #include "Foundation/NSArray.h" +/** + * Simple class for iterating over a collection of objects, usually returned + * from an [NSArray] or similar. + */ @implementation NSEnumerator +/** + * Returns all objects remaining in the enumeration as an array. + */ - (NSArray*) allObjects { NSMutableArray *array; @@ -54,6 +61,10 @@ return array; } +/** + * Returns next object in enumeration, or nil if none remain. Use code like + * while (object = [enumerator nextObject]) { ... }. + */ - (id) nextObject { [self subclassResponsibility:_cmd]; diff --git a/Source/NSException.m b/Source/NSException.m index 98f2a75b5..73d1a3912 100644 --- a/Source/NSException.m +++ b/Source/NSException.m @@ -40,7 +40,7 @@ NSString* const NSGenericException = @"NSGenericException"; /** - * An exception for caes where unexpected state is detected within an object + * An exception for cases where unexpected state is detected within an object. */ NSString* const NSInternalInconsistencyException = @"NSInternalInconsistencyException"; @@ -53,7 +53,7 @@ NSString* const NSInvalidArgumentException = @"NSInvalidArgumentException"; /** - * An exception used when the system faols to allocate required memory. + * An exception used when the system fails to allocate required memory. */ NSString* const NSMallocException = @"NSMallocException"; @@ -120,15 +120,16 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception) /**

- The NSException class helps manage errors in a program. It provides - a mechanism for lower-level methods to provide information about + The NSException class helps manage errors in a program. It + provides a mechanism for lower-level methods to provide information about problems to higher-level methods, which more often than not, have a better ability to decide what to do about the problems.

Exceptions are typically handled by enclosing a sensitive section - of code inside the macros NS_DURING and NS_HANDLER, and then - handling any problems after this, up to the NS_ENDHANDLER macro: + of code inside the macros NS_DURING and NS_HANDLER, + and then handling any problems after this, up to the + NS_ENDHANDLER macro:

NS_DURING @@ -141,9 +142,9 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception) NS_ENDHANDLER

- The local variable localException is the name of the exception - object you can use in the NS_HANDLER section. - The easiest way to cause an exeption is using the +raise:format:,... + The local variable localException is the name of the exception + object you can use in the NS_HANDLER section. + The easiest way to cause an exception is using the +raise:format:,... method.

*/ @@ -248,7 +249,7 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception) longjmp(handler->jumpState, 1); } -/** Returns the name of the exception */ +/** Returns the name of the exception. */ - (NSString*) name { if (_e_name != nil) @@ -261,7 +262,7 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception) } } -/** Returns the exception reason */ +/** Returns the exception reason. */ - (NSString*) reason { if (_e_reason != nil) @@ -274,7 +275,7 @@ _NSFoundationUncaughtExceptionHandler (NSException *exception) } } -/** Returns the exception userInfo dictionary */ +/** Returns the exception userInfo dictionary. */ - (NSDictionary*) userInfo { return _e_info; diff --git a/Source/NSFileHandle.m b/Source/NSFileHandle.m index fe5218860..2d9f8b346 100644 --- a/Source/NSFileHandle.m +++ b/Source/NSFileHandle.m @@ -52,12 +52,12 @@ static Class NSFileHandle_ssl_class = nil; /** *

- * NSFileHandler is a Class that provides a wrapper for accessing - * system files and other connections. You can open connections to a + * NSFileHandle is a class that provides a wrapper for accessing + * system files and socket connections. You can open connections to a * file using class methods such as +fileHandleForReadingAtPath:. *

*

- * GNUstep extends the use of this Class to allow you to create + * GNUstep extends the use of this class to allow you to create * network connections (sockets), secure connections and also allows * you to use compression with these files and connections (as long as * GNUstep Base was compiled with the zlib library). @@ -88,7 +88,7 @@ static Class NSFileHandle_ssl_class = nil; // Allocating and Initializing a FileHandle Object /** - * Returns an NSFileHandle object setup for reading from the + * Returns an NSFileHandle object set up for reading from the * file listed at path. If the file does not exist or cannot * be opened for some other reason, nil is returned. */ @@ -100,7 +100,7 @@ static Class NSFileHandle_ssl_class = nil; } /** - * Returns an NSFileHandle object setup for writing to the + * Returns an NSFileHandle object set up for writing to the * file listed at path. If the file does not exist or cannot * be opened for some other reason, nil is returned. */ @@ -112,7 +112,7 @@ static Class NSFileHandle_ssl_class = nil; } /** - * Returns an NSFileHandle object setup for updating (reading and + * Returns an NSFileHandle object setup for updating (reading and * writing) from the file listed at path. If the file does not exist * or cannot be opened for some other reason, nil is returned. */ @@ -124,9 +124,9 @@ static Class NSFileHandle_ssl_class = nil; } /** - * Returns an NSFileHandle object for the standard error descriptor. - * The returned object is a shared instance as there can only be one - * standard error per process. + * Returns an NSFileHandle object for the standard error + * descriptor. The returned object is a shared instance as there can only be + * one standard error per process. */ + (id) fileHandleWithStandardError { @@ -136,9 +136,9 @@ static Class NSFileHandle_ssl_class = nil; } /** - * Returns an NSFileHandle object for the standard input descriptor. - * The returned object is a shared instance as there can only be one - * standard input per process. + * Returns an NSFileHandle object for the standard input + * descriptor. The returned object is a shared instance as there can only be + * one standard input per process. */ + (id) fileHandleWithStandardInput { @@ -148,9 +148,9 @@ static Class NSFileHandle_ssl_class = nil; } /** - * Returns an NSFileHandle object for the standard output descriptor. - * The returned object is a shared instance as there can only be one - * standard output per process. + * Returns an NSFileHandle object for the standard output + * descriptor. The returned object is a shared instance as there can only be + * one standard output per process. */ + (id) fileHandleWithStandardOutput { @@ -173,17 +173,29 @@ static Class NSFileHandle_ssl_class = nil; return AUTORELEASE([o initWithNullDevice]); } +/** + * Initialize with desc, which can point to either a regular file or + * socket connection. + */ - (id) initWithFileDescriptor: (int)desc { return [self initWithFileDescriptor: desc closeOnDealloc: NO]; } +/** + * Initialize with desc, which can point to either a regular file or + * socket connection. Close desc when this instance is deallocated if + * flag is YES. + */ - (id) initWithFileDescriptor: (int)desc closeOnDealloc: (BOOL)flag { [self subclassResponsibility: _cmd]; return nil; } +/** + * Windows-Unix compatibility support. + */ - (id) initWithNativeHandle: (void*)hdl { return [self initWithNativeHandle: hdl closeOnDealloc: NO]; @@ -191,6 +203,10 @@ static Class NSFileHandle_ssl_class = nil; // This is the designated initializer. +/** + * + * Windows-Unix compatibility support. + */ - (id) initWithNativeHandle: (void*)hdl closeOnDealloc: (BOOL)flag { [self subclassResponsibility: _cmd]; @@ -199,12 +215,18 @@ static Class NSFileHandle_ssl_class = nil; // Returning file handles +/** + * Return the underlying file descriptor for this instance. + */ - (int) fileDescriptor { [self subclassResponsibility: _cmd]; return -1; } +/** + * Windows-Unix compatibility support. + */ - (void*) nativeHandle { [self subclassResponsibility: _cmd]; @@ -213,24 +235,41 @@ static Class NSFileHandle_ssl_class = nil; // Synchronous I/O operations +/** + * Synchronously returns data available through this file or connection. + * If the handle represents a file, the entire contents from current file + * pointer to end are returned. If this is a network connection, reads + * what is available, blocking if nothing is available. Raises + * NSFileHandleOperationException if problem encountered. + */ - (NSData*) availableData { [self subclassResponsibility: _cmd]; return nil; } +/** + * Reads up to maximum unsigned int bytes from file or communications + * channel into return data. + */ - (NSData*) readDataToEndOfFile { [self subclassResponsibility: _cmd]; return nil; } +/** + * Reads up to len bytes from file or communications channel into return data. + */ - (NSData*) readDataOfLength: (unsigned int)len { [self subclassResponsibility: _cmd]; return nil; } +/** + * Synchronously writes given data item to file or connection. + */ - (void) writeData: (NSData*)item { [self subclassResponsibility: _cmd]; @@ -239,11 +278,32 @@ static Class NSFileHandle_ssl_class = nil; // Asynchronous I/O operations +/** + * Asynchronously accept a stream-type socket connection and act as the + * (server) end of the communications channel. This instance should have + * been created by -initWithFileDescriptor: with a stream-type socket created + * by the appropriate system routine. Posts a + * NSFileHandleConnectionAcceptedNotification when connection + * initiated, returning an NSFileHandle for the client side with + * that notification. + */ - (void) acceptConnectionInBackgroundAndNotify { [self acceptConnectionInBackgroundAndNotifyForModes: nil]; } +/** + *

Asynchronously accept a stream-type socket connection and act as the + * (server) end of the communications channel. This instance should have + * been created by -initWithFileDescriptor: with a stream-type socket created + * by the appropriate system routine. Posts a + * NSFileHandleConnectionAcceptedNotification when connection + * initiated, returning an NSFileHandle for the client side with + * that notification.

+ * + *

The modes array specifies [NSRunLoop] modes that the notification can + * be posted in.

+ */ - (void) acceptConnectionInBackgroundAndNotifyForModes: (NSArray*)modes { [self subclassResponsibility: _cmd]; @@ -305,18 +365,30 @@ static Class NSFileHandle_ssl_class = nil; // Seeking within a file +/** + * Return current position in file, or raises exception if instance does + * not represent a regular file. + */ - (unsigned long long) offsetInFile { [self subclassResponsibility: _cmd]; return 0; } +/** + * Position file pointer at end of file, raising exception if instance does + * not represent a regular file. + */ - (unsigned long long) seekToEndOfFile { [self subclassResponsibility: _cmd]; return 0; } +/** + * Position file pointer at pos, raising exception if instance does + * not represent a regular file. + */ - (void) seekToFileOffset: (unsigned long long)pos { [self subclassResponsibility: _cmd]; @@ -325,16 +397,27 @@ static Class NSFileHandle_ssl_class = nil; // Operations on file +/** + * Disallows further reading from read-access files or connections, and sends + * EOF on write-access files or connections. Descriptor is only + * deleted when this instance is deallocated. + */ - (void) closeFile { [self subclassResponsibility: _cmd]; } +/** + * Flush in-memory buffer to file or connection, then return. + */ - (void) synchronizeFile { [self subclassResponsibility: _cmd]; } +/** + * Chops file beyond pos then sets file pointer to that point. + */ - (void) truncateFileAtOffset: (unsigned long long)pos { [self subclassResponsibility: _cmd]; @@ -365,12 +448,19 @@ NSString * const NSFileHandleReadToEndOfFileCompletionNotification // Exceptions +/** + * An exception used when a file error occurs. + */ NSString * const NSFileHandleOperationException = @"NSFileHandleOperationException"; // GNUstep class extensions +/** + * A set of convenience methods for utilizing the socket communications + * capabilities of the [NSFileHandle] class. + */ @implementation NSFileHandle (GNUstepExtensions) /** diff --git a/Source/NSFileManager.m b/Source/NSFileManager.m index 0cd0517fb..8d7e8ab3c 100644 --- a/Source/NSFileManager.m +++ b/Source/NSFileManager.m @@ -230,7 +230,11 @@ @end /* NSFileManager (PrivateMethods) */ /** - * This is the main class for management of the local filesystem. + * This is the main class for platform-independent management of the local + * filesystem, which allows you to read and save files, create/list + * directories, and move or delete files and directories. In addition to + * simply listing directories, you may obtain an [NSDirectoryEnumerator] + * instance for recursive directory contents enumeration. */ @implementation NSFileManager @@ -1378,54 +1382,54 @@ static NSFileManager* defaultManager = nil; /** * If a file (or directory etc) exists at the specified path, and can be - * queriesd for its attributes, this method returns a dictionary containing + * queried for its attributes, this method returns a dictionary containing * the various attributes of that file. Otherwise nil is returned.
* If the flag is NO and the file is a symbolic link, the attributes of - * the link itsself (rather than the file it points to) are returned.
+ * the link itself (rather than the file it points to) are returned.
*

* The dictionary keys for attributes are - *

* - * NSFileAppendOnly + * NSFileAppendOnly * NSNumber ... boolean - * NSFileCreationDate + * NSFileCreationDate * NSDate when the file was created (if supported) - * NSFileDeviceIdentifier + * NSFileDeviceIdentifier * NSNumber (identifies the device on which the file is stored) - * NSFileExtensionHidden + * NSFileExtensionHidden * NSNumber ... boolean - * NSFileGroupOwnerAccountName + * NSFileGroupOwnerAccountName * NSString name of the file group - * NSFileGroupOwnerAccountID + * NSFileGroupOwnerAccountID * NSNumber ID of the file group - * NSFileHFSCreatorCode + * NSFileHFSCreatorCode * NSNumber not used - * NSFileHFSTypeCode + * NSFileHFSTypeCode * NSNumber not used - * NSFileImmutable + * NSFileImmutable * NSNumber ... boolean - * NSFileModificationDate + * NSFileModificationDate * NSDate when the file was last modified - * NSFileOwnerAccountName + * NSFileOwnerAccountName * NSString name of the file owner - * NSFileOwnerAccountID + * NSFileOwnerAccountID * NSNumber ID of the file owner - * NSFilePosixPermissions + * NSFilePosixPermissions * NSNumber posix access permissions mask - * NSFileReferenceCount + * NSFileReferenceCount * NSNumber number of links to this file - * NSFileSize + * NSFileSize * NSNumber size of the file in bytes - * NSFileSystemFileNumber + * NSFileSystemFileNumber * NSNumber the identifier for the file on the filesystem - * NSFileSystemNumber + * NSFileSystemNumber * NSNumber the filesystem on which the file is stored - * NSFileType + * NSFileType * NSString the type of file * *

- * The NSDictionary class also has a set of accessor methods which - * enable you to get at file attribute information more efficiently + * The [NSDictionary] class also has a set of convenience accessor methods + * which enable you to get at file attribute information more efficiently * than using the keys above to extract it. You should generally * use the accessor methods where they are available. *

@@ -1461,15 +1465,15 @@ static NSFileManager* defaultManager = nil; * Returns a dictionary containing the filesystem attributes for the * specified path (or nil if the path is not valid).
* - * NSFileSystemSize + * NSFileSystemSize * NSNumber the size of the filesystem in bytes - * NSFileSystemFreeSize + * NSFileSystemFreeSize * NSNumber the amount of unused space on the filesystem in bytes - * NSFileSystemNodes + * NSFileSystemNodes * NSNumber the number of nodes in use to store files - * NSFileSystemFreeNodes + * NSFileSystemFreeNodes * NSNumber the number of nodes available to create files - * NSFileSystemNumber + * NSFileSystemNumber * NSNumber the identifying number for the filesystem * */ @@ -1709,11 +1713,11 @@ static NSFileManager* defaultManager = nil; } /** - * Convert from OpenStep internal path format (unix-style) to a string in + * Convert from OpenStep internal path format (Unix-style) to a string in * the local filesystem format, suitable for passing to system functions.
- * Under unix, this simply standardizes the path and converts to a + * Under Unix, this simply standardizes the path and converts to a * C string.
- * Under windoze, this attempts to use local conventions to convert to a + * Under Windoze, this attempts to use local conventions to convert to a * windows path. In GNUstep, the conventional unix syntax '~user/...' can * be used to indicate a windoze drive specification by using the drive * letter in place of the username, and the syntax '~@server/...' can be used @@ -1741,7 +1745,7 @@ static NSFileManager* defaultManager = nil; l = strlen(c_path); if (l >= 2 && c_path[0] == '~' && c_path[1] == '@') { - // Conver to windows UNC path. + // Convert to windows UNC path. newpath = [NSString stringWithFormat: @"//%s", &c_path[2]]; } else if (l >= 2 && c_path[0] == '~' && isalpha(c_path[1]) @@ -1820,7 +1824,7 @@ static NSFileManager* defaultManager = nil; /* * NB ... Don't standardize path, since that would automatically * follow symbolic links ... and mess up any code wishing to - * examine the link itsself. + * examine the link itself. */ return [path cString]; #endif @@ -2010,15 +2014,22 @@ inline char *append_file_to_path (const char *path, const char *file) static SEL swfsSel = 0; /** - * NSDirectoryEnumerator implementation
+ *

This is a subclass of NSEnumerator which provides a full + * listing of all the files beneath a directory and its subdirectories. + * Instances can be obtained through [NSFileManager-enumeratorAtPath:], + * or through an initializer in this class. (For compatibility with OS X, + * use the NSFileManager method.)

* + *

This implementation is optimized and performance should be comparable + * to the speed of standard Unix tools for large directories.

+ */ +@implementation NSDirectoryEnumerator +/* * The Objective-C interface hides a traditional C implementation. * This was the only way I could get near the speed of standard unix * tools for big directories. */ -@implementation NSDirectoryEnumerator - + (void) initialize { if (self == [NSDirectoryEnumerator class]) @@ -2031,11 +2042,21 @@ static SEL swfsSel = 0; // Initializing +/** + * Initialize instance to enumerate contents at path, which should be a + * directory and can be specified in relative or absolute, and may include + * Unix conventions like '~' for user home directory, which will + * be appropriately converted on Windoze systems. The justContents flag, if + * set, is equivalent to recurseIntoSubdirectories = NO and followSymlinks = + * NO, but the implementation will be made more efficient. + */ - (id) initWithDirectoryPath: (NSString*)path recurseIntoSubdirectories: (BOOL)recurse followSymlinks: (BOOL)follow justContents: (BOOL)justContents { +//TODO: the justContents flag is currently basically useless and should be +// removed DIR *dir_pointer; const char *topPath; @@ -2177,6 +2198,8 @@ static SEL swfsSel = 0; return_file_name = append_file_to_path(dir.path, dirbuf->d_name); /* TODO - can this one can be removed ? */ + /* ... seems like it can... */ + /* also, what if justContents=YES *and* isRecursive=YES? */ if (!_flags.justContents) { _current_file_path = append_file_to_path(_top_path, @@ -2250,10 +2273,9 @@ static SEL swfsSel = 0; @end /* NSDirectoryEnumerator */ -/* - * Attributes dictionary access +/** + * Convenience methods for accessing named file attributes in a dictionary. */ - @implementation NSDictionary(NSFileAttributes) /** @@ -2272,11 +2294,17 @@ static SEL swfsSel = 0; return [[self objectForKey: NSFileExtensionHidden] boolValue]; } +/** + * Returns HFS creator attribute (OS X). + */ - (int) fileHFSCreatorCode { return [[self objectForKey: NSFileHFSCreatorCode] intValue]; } +/** + * Returns HFS type code attribute (OS X). + */ - (int) fileHFSTypeCode { return [[self objectForKey: NSFileHFSTypeCode] intValue]; diff --git a/Source/NSHashTable.m b/Source/NSHashTable.m index 7d7e81bd7..5e0b3f23a 100644 --- a/Source/NSHashTable.m +++ b/Source/NSHashTable.m @@ -183,7 +183,9 @@ NSCountHashTable(NSHashTable *table) /** * Create a new hash table by calling NSCreateHashTableWithZone() using - * NSDefaultMallocZone().
+ * NSDefaultMallocZone(). callbacks provides five helper functions used by + * the main implementation. See the NSHashTableCallbacks documentation + * for more information.
* If capacity is small or 0, then the returned * table has a reasonable (but still small) capacity. */ diff --git a/Source/NSIndexSet.m b/Source/NSIndexSet.m index b2a67f4da..87704f4af 100644 --- a/Source/NSIndexSet.m +++ b/Source/NSIndexSet.m @@ -91,7 +91,7 @@ static unsigned posForIndex(GSIArray array, unsigned index) return AUTORELEASE(o); } -+ (id) indexSetWithIndex: (unsigned int)anIndex; ++ (id) indexSetWithIndex: (unsigned int)anIndex { id o = [self allocWithZone: NSDefaultMallocZone()]; @@ -99,7 +99,7 @@ static unsigned posForIndex(GSIArray array, unsigned index) return AUTORELEASE(o); } -+ (id) indexSetWithIndexesInRange: (NSRange)aRange; ++ (id) indexSetWithIndexesInRange: (NSRange)aRange { id o = [self allocWithZone: NSDefaultMallocZone()]; diff --git a/Source/NSInvocation.m b/Source/NSInvocation.m index 41d685db8..b99edfbfe 100644 --- a/Source/NSInvocation.m +++ b/Source/NSInvocation.m @@ -58,11 +58,11 @@ static Class NSInvocation_concrete_class; /** - *

The NSInvocation class implements a mechanism of constructing - * messages (as NSInvocation instances), sending these to other + *

The NSInvocation class implements a mechanism of constructing + * messages (as NSInvocation instances), sending these to other * objects, and handling the returned values. *

- *

An NSInvocation object may contain a target object to which a + *

An NSInvocation object may contain a target object to which a * message can be sent, or may send the message to an arbitrary object.
* Each message consists of a selector for that method and an argument * list. Once the message has been sent, the invocation will contain @@ -78,8 +78,8 @@ static Class NSInvocation_concrete_class; * object to which it was sent. *

*

Related to the class are two convenience macros ... NS_MESSAGE() - * and NS_INVOCATION() to allow easy construction of invocations with - * all the arguments set up. + * and NS_INVOCATION() ... to allow easy construction of invocations + * with all the arguments set up. *

*/ @implementation NSInvocation @@ -717,7 +717,7 @@ _arg_addr(NSInvocation *inv, int index) /** * Provides some minor extensions and some utility methods to aid - * integration of NSInvocation with the ObjectiveC runtime. + * integration of NSInvocation with the Objective-C runtime. */ @implementation NSInvocation (GNUstep) @@ -903,7 +903,7 @@ _arg_addr(NSInvocation *inv, int index) /** * Sets the flag to tell the invocation that it should actually invoke a * method in the superclass of the target rather than the method of the - * target itsself.
+ * target itself.
* This extension permits an invocation to act like a regular method * call sent to super in the method of a class. */ diff --git a/Source/NSKeyedArchiver.m b/Source/NSKeyedArchiver.m index 1a1b2461f..d3b76b951 100644 --- a/Source/NSKeyedArchiver.m +++ b/Source/NSKeyedArchiver.m @@ -52,6 +52,10 @@ #undef _IN_NSKEYEDARCHIVER_M /* Exceptions */ + +/** + * An archiving error has occurred. + */ NSString * const NSInvalidArchiveOperationException = @"NSInvalidArchiveOperationException"; @@ -316,7 +320,7 @@ static NSDictionary *makeReference(unsigned ref) } /* - * At last, get the object to encode itsself. Save and restore the + * At last, get the object to encode itself. Save and restore the * current object scope of course. */ _enc = m; diff --git a/Source/NSKeyedUnarchiver.m b/Source/NSKeyedUnarchiver.m index 48a8d983f..df42bd600 100644 --- a/Source/NSKeyedUnarchiver.m +++ b/Source/NSKeyedUnarchiver.m @@ -45,6 +45,9 @@ #include #undef _IN_NSKEYEDUNARCHIVER_M +/** + * An unarchiving error has occurred. + */ NSString * const NSInvalidUnarchiveOperationException = @"NSInvalidUnarchiveOperationException"; diff --git a/Source/NSLock.m b/Source/NSLock.m index 64bd86f84..8e649e342 100644 --- a/Source/NSLock.m +++ b/Source/NSLock.m @@ -132,14 +132,13 @@ NSString *NSRecursiveLockException = @"NSRecursiveLockException"; // Simplest lock for protecting critical sections of code /** - * An NSLock is used in multi-threaded applications to protect critical - * pieces of code. While one thread holds a lock within a piece of code, - * another thread cannot execute that code until the first thread has - * given up it's hold on the lock. The limitation of NSLock is that - * you can only lock an - * NSLock once and it must be unlocked before it can be aquired again.
- * Other lock classes, notably NSRecursiveLock, have - * different restrictions. + * An NSLock is used in multi-threaded applications to protect + * critical pieces of code. While one thread holds a lock within a piece of + * code, another thread cannot execute that code until the first thread has + * given up its hold on the lock. The limitation of NSLock is + * that you can only lock an NSLock once and it must be unlocked + * before it can be aquired again.
Other lock classes, notably + * [NSRecursiveLock], have different restrictions. */ @implementation NSLock @@ -567,8 +566,8 @@ NSString *NSRecursiveLockException = @"NSRecursiveLockException"; /** - * See NSLock for more information about what a lock is. A recursive - * lock extends NSLock in that you can lock a recursive lock multiple + * See [NSLock] for more information about what a lock is. A recursive + * lock extends [NSLock] in that you can lock a recursive lock multiple * times. Each lock must be balanced by a cooresponding unlock, and the * lock is not released for another thread to aquire until the last * unlock call is made (corresponding to the first lock message). diff --git a/Source/NSMapTable.m b/Source/NSMapTable.m index d12fa72aa..889eb54eb 100644 --- a/Source/NSMapTable.m +++ b/Source/NSMapTable.m @@ -377,7 +377,7 @@ NSMapGet(NSMapTable *table, const void *key) /** * Adds the key and value to table.
* If an equal key is already in table, replaces its mapped value - * with the new one, without changing the key itsself.
+ * with the new one, without changing the key itself.
* If key is equal to the notAKeyMarker field of the table's * NSMapTableKeyCallBacks, raises an NSInvalidArgumentException. */ diff --git a/Source/NSMessagePort.m b/Source/NSMessagePort.m index 4334ba401..144c07a1a 100644 --- a/Source/NSMessagePort.m +++ b/Source/NSMessagePort.m @@ -1226,7 +1226,7 @@ static int unique_index = 0; /* * This is the preferred initialisation method for NSMessagePort * - * 'name' is the name of the socket in the port directory + * 'socketName' is the name of the socket in the port directory */ + (NSMessagePort*) _portWithName: (const unsigned char *)socketName listener: (BOOL)shouldListen @@ -1642,11 +1642,6 @@ static int unique_index = 0; } } -/* - * This is called when a tcp/ip socket connection is broken. We remove the - * connection handle from this port and, if this was the last handle to a - * remote port, we invalidate the port. - */ - (void) removeHandle: (GSMessageHandle*)handle { M_LOCK(myLock); @@ -1753,7 +1748,7 @@ static int unique_index = 0; header = [components objectAtIndex: 0]; /* * The Item header contains the item type and the length of the - * data in the item (excluding the item header itsself). + * data in the item (excluding the item header itself). */ hLength = [header length]; l = hLength - sizeof(GSPortItemHeader); diff --git a/Source/NSMessagePortNameServer.m b/Source/NSMessagePortNameServer.m index ddaa0d2a7..3e3472d97 100644 --- a/Source/NSMessagePortNameServer.m +++ b/Source/NSMessagePortNameServer.m @@ -74,7 +74,12 @@ static void clean_up_names(void) } } - +/** + * Subclass of [NSPortNameServer] taking/returning instances of [NSMessagePort]. + * Port removal functionality is not supported; if you want to cancel a service, + * you have to destroy the port (invalidate the [NSMessagePort] given to + * [NSPortNameServer-registerPort:forName:]). + */ @implementation NSMessagePortNameServer + (void) initialize @@ -88,6 +93,9 @@ static void clean_up_names(void) } } +/** + * Obtain single instance for this host. + */ + (id) sharedInstance { if (defaultServer == nil) diff --git a/Source/NSNotification.m b/Source/NSNotification.m index 13ee59684..937683977 100644 --- a/Source/NSNotification.m +++ b/Source/NSNotification.m @@ -29,6 +29,15 @@ #include "Foundation/NSCoder.h" #include "Foundation/NSString.h" +/** + *

Represents a notification for posting to an [NSNotificationCenter]. + * Consists of a name, an object, and an optional dictionary. The + * notification center will check for observers registered to receive + * either notifications with the name, the object, or both and pass the + * notification instance on to them.

+ *

This class is actually the interface for a class cluster, so instances + * will be of a (private) subclass.

+ */ @implementation NSNotification static Class abstractClass = 0; @@ -55,8 +64,7 @@ static Class concreteClass = 0; } /** - * Create a new autoreleased notification. Concrete subclasses override - * this method to create actual notification objects. + * Create a new autoreleased notification. */ + (NSNotification*) notificationWithName: (NSString*)name object: (id)object @@ -81,8 +89,7 @@ static Class concreteClass = 0; /** * The abstract class implements a copy as a simple retain ... - * subclasses should override this to perform more intelligent - * copy operations. + * subclasses override to perform more intelligent copy operations. */ - (id) copyWithZone: (NSZone*)zone { @@ -112,8 +119,7 @@ static Class concreteClass = 0; } /** - * Concrete subclasses of NSNotification are responsible for - * implementing this method to return the notification name. + * Returns the notification name. */ - (NSString*) name { @@ -122,8 +128,7 @@ static Class concreteClass = 0; } /** - * Concrete subclasses of NSNotification are responsible for - * implementing this method to return the notification object. + * Returns the notification object. */ - (id) object { @@ -132,8 +137,7 @@ static Class concreteClass = 0; } /** - * Concrete subclasses of NSNotification are responsible for - * implementing this method to return the notification user information. + * Returns the notification user information. */ - (NSDictionary*) userInfo { diff --git a/Source/NSNotificationCenter.m b/Source/NSNotificationCenter.m index f7617a55a..a827945e0 100644 --- a/Source/NSNotificationCenter.m +++ b/Source/NSNotificationCenter.m @@ -37,7 +37,7 @@ /** - * Concrete class implementing NSNotification + * Concrete class implementing NSNotification. */ @interface GSNotification : NSNotification { @@ -539,6 +539,24 @@ purgeMapNode(GSIMapTable map, GSIMapNode node, id observer) +/** + *

GNUstep provides a framework for sending messages between objects within + * a process called notifications. Objects register with an + * NSNotificationCenter to be informed whenever other objects + * post [NSNotification]s to it matching certain criteria. The notification + * center processes notifications synchronously -- that is, control is only + * returned to the notification poster once every recipient of the + * notification has received it and processed it. Asynchronous processing is + * possible using an [NSNotificationQueue].

+ * + *

Obtain an instance using the +defaultCenter method.

+ * + *

In a multithreaded process, notifications are always sent on the thread + * that they are posted from.

+ * + *

Use the [NSDistributedNotificationCenter] for interprocess + * communications on the same machine.

+ */ @implementation NSNotificationCenter /* The default instance, most often the only one created. @@ -564,6 +582,11 @@ static NSNotificationCenter *default_center = nil; } } +/** + * Returns the default notification center being used for this task (process). + * This is used for all notifications posted by the Base library unless + * otherwise noted. + */ + (NSNotificationCenter*) defaultCenter { return default_center; @@ -599,6 +622,21 @@ static NSNotificationCenter *default_center = nil; /* Adding new observers. */ +/** + *

Registers observer to receive notifications with the name + * notificationName and/or containing object (one or both of these two must be + * non-nil; nil acts like a wildcard). When a notification of name name + * containing object is posted, observer receives a selector message with this + * notification as the argument. The notification center waits for the + * observer to finish processing the message, then informs the next registree + * matching the notification, and after all of this is done, control returns + * to the poster of the notification. Therefore the processing in the + * selector implementation should be short.

+ * + *

The notification center does not retain observer or object. Therefore, + * you should always send removeObserver: or removeObserver:name:object: to + * the notification center before releasing these objects.

+ */ - (void) addObserver: (id)observer selector: (SEL)selector name: (NSString*)name @@ -710,6 +748,14 @@ static NSNotificationCenter *default_center = nil; unlockNCTable(TABLE); } +/** + * Deregisters observer for notifications matching name and/or object. If + * either or both is nil, they act like wildcards. The observer may still + * remain registered for other notifications; use -removeObserver: to remove + * it from all. If observer is nil, the effect is to remove all registrees + * for the specified notifications, unless both observer and name are nil, in + * which case nothing is done. + */ - (void) removeObserver: (id)observer name: (NSString*)name object: (id)object @@ -866,9 +912,10 @@ static NSNotificationCenter *default_center = nil; unlockNCTable(TABLE); } -/* Remove all records pertaining to OBSERVER. For instance, this - should be called before the OBSERVER is -dealloc'ed. */ - +/** + * Deregisters observer from all notifications. This should be called before + * the observer is deallocated. +*/ - (void) removeObserver: (id)observer { if (observer == nil) diff --git a/Source/NSNotificationQueue.m b/Source/NSNotificationQueue.m index 8af75ae6f..67a69668e 100644 --- a/Source/NSNotificationQueue.m +++ b/Source/NSNotificationQueue.m @@ -284,8 +284,22 @@ add_to_queue(NSNotificationQueueList *queue, NSNotification *notification, forModes: (NSArray*)modes; @end +/** + * This class supports asynchronous posting of [NSNotification]s to an + * [NSNotificationCenter]. The method to add a notification to the queue + * returns immediately. The queue will periodically post its oldest + * notification to the notification center. In a multithreaded process, + * notifications are always sent on the thread that they are posted from. + */ @implementation NSNotificationQueue + +/** + * Returns the default notification queue for use in this thread. It will + * always post notifications to the default notification center (for the + * entire task, which may have multiple threads and therefore multiple + * notification queues). + */ + (NSNotificationQueue*) defaultQueue { NotificationQueueList *list; @@ -309,6 +323,10 @@ add_to_queue(NSNotificationQueueList *queue, NSNotification *notification, [NSNotificationCenter defaultCenter]]; } +/** + * Initialize a new instance to post notifications to the given + * notificationCenter (instead of the default). + */ - (id) initWithNotificationCenter: (NSNotificationCenter*)notificationCenter { _zone = [self zone]; @@ -361,6 +379,17 @@ add_to_queue(NSNotificationQueueList *queue, NSNotification *notification, /* Inserting and Removing Notifications From a Queue */ +/** + * Immediately remove all notifications from queue matching notification on + * name and/or object as specified by coalesce mask, which is an OR + * ('|') of the options + * NSNotificationCoalescingOnName, + * NSNotificationCoalescingOnSender (object), and + * NSNotificationNoCoalescing (match only the given instance + * exactly). If both of the first options are specified, notifications must + * match on both attributes (not just either one). Removed notifications are + * not posted. + */ - (void) dequeueNotificationsMatching: (NSNotification*)notification coalesceMask: (unsigned int)coalesceMask { @@ -378,6 +407,7 @@ add_to_queue(NSNotificationQueueList *queue, NSNotification *notification, for (item = _asapQueue->tail; item; item = next) { next = item->next; + //PENDING: should object comparison be '==' instead of isEqual?! if ((object == item->object) && [name isEqual: item->name]) { remove_from_queue(_asapQueue, item, _zone); @@ -447,6 +477,12 @@ add_to_queue(NSNotificationQueueList *queue, NSNotification *notification, } } +/** + * Sets notification to be posted to notification center at time dependent on + * postingStyle, which may be either NSPostNow (synchronous post), + * NSPostASAP (post soon), or NSPostWhenIdle (post + * when runloop is idle). + */ - (void) enqueueNotification: (NSNotification*)notification postingStyle: (NSPostingStyle)postingStyle { @@ -457,6 +493,17 @@ add_to_queue(NSNotificationQueueList *queue, NSNotification *notification, forModes: nil]; } +/** + * Sets notification to be posted to notification center at time dependent on + * postingStyle, which may be either NSPostNow (synchronous + * post), NSPostASAP (post soon), or NSPostWhenIdle + * (post when runloop is idle). coalesceMask determines whether this + * notification should be considered same as other ones already on the queue, + * in which case they are removed through a call to + * -dequeueNotificationsMatching:coalesceMask: . The modes argument + * determines which [NSRunLoop] mode notification may be posted in (nil means + * all modes). + */ - (void) enqueueNotification: (NSNotification*)notification postingStyle: (NSPostingStyle)postingStyle coalesceMask: (unsigned int)coalesceMask diff --git a/Source/NSNumber.m b/Source/NSNumber.m index 287b8ff99..0cc255036 100644 --- a/Source/NSNumber.m +++ b/Source/NSNumber.m @@ -803,50 +803,11 @@ static Class doubleNumberClass; return NSCopyObject(self, 0, zone); } -/** - * Returns the string representation of this number using a non-localised - * conversion (decimal point is '.' irrespective of the locale). - */ - (NSString*) description { return [self descriptionWithLocale: nil]; } -/** - *

- * Produces a string representation of the number. For a boolean - * this will be either 'true' or 'false'. For other numbers the - * format is produced using the initWithFormat:locale:... method - * of NSString, and the format depends on the type of number as - * follows - - *

- * - * char - * %i - * short - * %hi - * int - * %i - * long - * %li - * long long - * %lli - * unsigned char - * %u - * unsigned short - * %hu - * unsigned int - * %u - * unsigned long - * %lu - * unsigned long long - * %llu - * float - * %0.7g - * double - * %0.16g - * - */ - (NSString*) descriptionWithLocale: (NSDictionary*)locale { NSString *result = nil; diff --git a/Source/NSNumberFormatter.m b/Source/NSNumberFormatter.m index 192aa8ec5..cfc55528b 100644 --- a/Source/NSNumberFormatter.m +++ b/Source/NSNumberFormatter.m @@ -366,6 +366,7 @@ _thousandSeparator = 0; } +//FIXME - not implemented !? - (NSString*) stringForObjectValue: (id)anObject { if (nil == anObject) diff --git a/Source/NSObject.m b/Source/NSObject.m index 67a5b31a0..3a277ae60 100644 --- a/Source/NSObject.m +++ b/Source/NSObject.m @@ -781,7 +781,7 @@ GSDescriptionForClassMethod(pcl self, SEL aSel) /** *

* NSObject is the root class (a root class is - * a class with no superclass) of the gnustep base library + * a class with no superclass) of the GNUstep base library * class hierarchy, so all classes normally inherit from * NSObject. There is an exception though: * NSProxy (which is used for remote messaging) @@ -792,16 +792,16 @@ GSDescriptionForClassMethod(pcl self, SEL aSel) * your own classes should inherit (directly or indirectly) * from NSObject (or in special cases from * NSProxy). NSObject provides - * the basic common functionality shared by all gnustep + * the basic common functionality shared by all GNUstep * classes and objects. *

*

* The essential methods which must be implemented by all - * classes for their instances to be usable within gnustep + * classes for their instances to be usable within GNUstep * are declared in a separate protocol, which is the * NSObject protocol. Both * NSObject and NSProxy conform to - * this protocol, which means all objects in a gnustep + * this protocol, which means all objects in a GNUstep * application will conform to this protocol (btw, if you * don't find a method of NSObject you are * looking for in this documentation, make sure you also @@ -813,7 +813,7 @@ GSDescriptionForClassMethod(pcl self, SEL aSel) * implement a new root class. If you do, you need to make * sure that your root class conforms (at least) to the * NSObject protocol, otherwise it will not - * interact correctly with the gnustep framework. Said + * interact correctly with the GNUstep framework. Said * that, I must note that I have never seen a case in which * a new root class is needed. *

@@ -848,12 +848,22 @@ GSDescriptionForClassMethod(pcl self, SEL aSel) } #if GS_WITH_GC +/** + * A utility method used when garbage collection is enabled. Can be ignored. + */ + (BOOL) requiresTypedMemory { return NO; } #endif +/** + * This message is sent to a class once just before it is used for the first + * time. If class has a superclass, its implementation of +initialize is + * called first. You can implement +initialize in your own class if you need + * to. NSObject's implementation handles essential root object and base + * library initialization. + */ + (void) initialize { if (self == [NSObject class]) @@ -1194,7 +1204,7 @@ GSDescriptionForClassMethod(pcl self, SEL aSel) * If you have allocated the memory using a non-standard mechanism, you * will not call the superclass (NSObject) implementation of the method * as you will need to handle the deallocation specially.
- * In some circumstances, an object may wish to prevent itsself from + * In some circumstances, an object may wish to prevent itself from * being deallocated, it can do this simply be refraining from calling * the superclass implementation. *

@@ -1204,6 +1214,9 @@ GSDescriptionForClassMethod(pcl self, SEL aSel) NSDeallocateObject (self); } +/** + * This method is an anachronism. Do not use it. + */ - (id) free { [NSException raise: NSGenericException @@ -1229,7 +1242,7 @@ GSDescriptionForClassMethod(pcl self, SEL aSel) } /** - * Returns the super class from which the recevier was derived. + * Returns the super class from which the receiver was derived. */ + (Class) superclass { @@ -1237,7 +1250,7 @@ GSDescriptionForClassMethod(pcl self, SEL aSel) } /** - * Returns the super class from which the receviers class was derived. + * Returns the super class from which the receivers class was derived. */ - (Class) superclass { @@ -1399,7 +1412,7 @@ GSDescriptionForClassMethod(pcl self, SEL aSel) /* * If there are protocols that this class conforms to, * the method may be listed in a protocol with more - * detailed type information than in the class itsself + * detailed type information than in the class itself * and we must therefore use the information from the * protocol. * This is because protocols also carry information @@ -1526,26 +1539,61 @@ GSDescriptionForClassMethod(pcl self, SEL aSel) return self; } +// FIXME - should this be added (as in OS X) now that we have NSKeyedArchiver? +// - (Class) classForKeyedArchiver +// { +// return [self classForArchiver]; +// } + +/** + * Override to substitute class when an instance is being archived by an + * [NSArchiver]. Default implementation returns -classForCoder. + */ - (Class) classForArchiver { return [self classForCoder]; } +/** + * Override to substitute class when an instance is being serialized by an + * [NSCoder]. Default implementation returns [self class] (no + * substitution). + */ - (Class) classForCoder { return [self class]; } +/** + * Override to substitute class when an instance is being serialized by an + * [NSPortCoder]. Default implementation returns -classForCoder . + */ - (Class) classForPortCoder { return [self classForCoder]; } +// FIXME - should this be added (as in OS X) now that we have NSKeyedArchiver? +// - (id) replacedmentObjectForKeyedArchiver: (NSKeyedArchiver *)keyedArchiver +// { +// return [self replacementObjectForCoder: (NSArchiver *)keyedArchiver]; +// } + +/** + * Override to substitute another object for this instance when being archived + * by given [NSArchiver]. Default implementation returns + * -replacementObjectForCoder:. + */ - (id) replacementObjectForArchiver: (NSArchiver*)anArchiver { return [self replacementObjectForCoder: (NSCoder*)anArchiver]; } +/** + * Override to substitute another object for this instance when being + * serialized by given [NSCoder]. Default implementation returns + * self. + */ - (id) replacementObjectForCoder: (NSCoder*)anEncoder { return self; @@ -1943,7 +1991,9 @@ GSDescriptionForClassMethod(pcl self, SEL aSel) } /** - * Returns the version number of the receiving class. + * Returns the version number of the receiving class. This will default to + * a number assigned by the Objective C compiler if [NSObject -setVersion] has + * not been called. */ + (int) version { @@ -1951,7 +2001,7 @@ GSDescriptionForClassMethod(pcl self, SEL aSel) } /** - * Sets the version number of the receiving class. + * Sets the version number of the receiving class. Should be nonnegative. */ + (id) setVersion: (int)aVersion { @@ -1966,10 +2016,16 @@ GSDescriptionForClassMethod(pcl self, SEL aSel) @end +/** + * Methods for compatibility with the NEXTSTEP (pre-OpenStep) 'Object' class. + */ @implementation NSObject (NEXTSTEP) /* NEXTSTEP Object class compatibility */ +/** + * Logs a message. Deprecated. Use NSLog() in new code. + */ - (id) error: (const char *)aString, ... { #define FMT "error: %s (%s)\n%s\n" @@ -2088,6 +2144,10 @@ GSDescriptionForClassMethod(pcl self, SEL aSel) +/** + * Some non-standard extensions mainly needed for backwards compatibility + * and internal utility reasons. + */ @implementation NSObject (GNUstep) /* GNU Object class compatibility */ @@ -2263,24 +2323,37 @@ GSDescriptionForClassMethod(pcl self, SEL aSel) return class_get_version (self); } -// These are used to write or read the instance variables -// declared in this particular part of the object. Subclasses -// should extend these, by calling [super read/write: aStream] -// before doing their own archiving. These methods are private, in -// the sense that they should only be called from subclasses. +//NOTE: original comments included the following excerpt, however it is +// probably not relevant now since the implementations are stubbed out. +// Subclasses should extend these, by calling +// [super read/write: aStream] before doing their own archiving. These +// methods are private, in the sense that they should only be called from +// subclasses. +/** + * Originally used to read the instance variables declared in this + * particular part of the object from a stream. Currently stubbed out. + */ - (id) read: (TypedStream*)aStream { // [super read: aStream]; return self; } +/** + * Originally used to write the instance variables declared in this + * particular part of the object to a stream. Currently stubbed out. + */ - (id) write: (TypedStream*)aStream { // [super write: aStream]; return self; } +/** + * Originally used before [NSCoder] and related classes existed. Currently + * stubbed out. + */ - (id) awake { // [super awake]; diff --git a/Source/NSPort.m b/Source/NSPort.m index c671f8050..1af30182a 100644 --- a/Source/NSPort.m +++ b/Source/NSPort.m @@ -39,6 +39,10 @@ @implementation NSPort +/** + * Exception raised if a timeout occurs during a port send or receive + * operation. + */ NSString * const NSPortTimeoutException = @"NSPortTimeoutException"; Class NSPort_abstract_class; diff --git a/Source/NSProcessInfo.m b/Source/NSProcessInfo.m index a71354e71..a8f883dc6 100644 --- a/Source/NSProcessInfo.m +++ b/Source/NSProcessInfo.m @@ -145,9 +145,17 @@ Please report the error to bug-gnustep@gnu.org.\n\n" } @end + /************************************************************************* *** NSProcessInfo implementation *************************************************************************/ + +/** + * Instances of this class encapsulate information on the current process. + * For example, you can get the arguments, environment variables, host name, + * or process name. There is only one instance per process, for obvious + * reasons, and it may be obtained through the +processInfo method. + */ @implementation NSProcessInfo /************************************************************************* *** Static global vars @@ -912,6 +920,10 @@ int main(int argc, char *argv[], char *env[]) @end +/** + * Provides GNUstep-specific methods for controlled debug logging (a GNUstep + * facility) and an internal/developer-related method. + */ @implementation NSProcessInfo (GNUstep) static BOOL debugTemporarilyDisabled = NO; diff --git a/Source/NSProtocolChecker.m b/Source/NSProtocolChecker.m index 742190ea6..c2d892734 100644 --- a/Source/NSProtocolChecker.m +++ b/Source/NSProtocolChecker.m @@ -33,6 +33,23 @@ #include "Foundation/NSInvocation.h" #include "Foundation/NSMethodSignature.h" +/** + * The NSProtocolChecker and NSProxy classes provide message filtering and + * forwarding capabilities. If you wish to ensure at runtime that a given + * object will only be sent messages in a certain protocol, you create an + * NSProtocolChecker instance with the protocol and the object as + * arguments- + + + id versatileObject = [[ClassWithManyMethods alloc] init]; + id narrowObject = [NSProtocolChecker protocolCheckerWithTarget: versatileObject + protocol: @protocol(SomeSpecificProtocol)]; + return narrowObject; + + + * This is often used in conjunction with distributed objects to expose only a + * subset of an objects methods to remote processes + */ @implementation NSProtocolChecker /** @@ -95,9 +112,10 @@ return 0; } -/* +/** * Forwards any message to the delegate if the method is declared in - * the checker's protocol; otherwise raises an NSInvalidArgumentException. + * the checker's protocol; otherwise raises an + * NSInvalidArgumentException. */ - (void) forwardInvocation: (NSInvocation*)anInvocation { @@ -150,7 +168,7 @@ * delegate. Thus, the checker can be vended in lieu of anObject to * restrict the messages that can be sent to anObject. If any method * in the protocol returns anObject, the checker will replace the returned - * value with itsself rather than the target object.
+ * value with itself rather than the target object.
* Returns the new instance. */ - (id) initWithTarget: (NSObject*)anObject protocol: (Protocol*)aProtocol @@ -216,7 +234,7 @@ /* * If there are protocols that this class conforms to, * the method may be listed in a protocol with more - * detailed type information than in the class itsself + * detailed type information than in the class itself * and we must therefore use the information from the * protocol. * This is because protocols also carry information diff --git a/Source/NSProxy.m b/Source/NSProxy.m index 9786487dd..e8ed3b722 100644 --- a/Source/NSProxy.m +++ b/Source/NSProxy.m @@ -47,12 +47,17 @@ extern BOOL __objc_responds_to(id, SEL); #endif /** - * The NSProxy class provides a basic implementation of a class whose + *

The NSProxy class provides a basic implementation of a class whose * instances are used to stand in for other objects.
* The class provides the most basic methods of NSObject, and expects * messages for other methods to be forwarded to the real * object represented by the proxy. You must subclass NSProxy to - * implement -forwardInvocation: to these real objects. + * implement -forwardInvocation: to these real objects.

+ * + *

Note that NSProxy is a different sort of class than others + * in the GNUstep Base library in that it is the only example of a root class + * besides [NSObject]. Thus, it defines its own isa + * variable and implements the NSObject protocol.

*/ @implementation NSProxy @@ -74,7 +79,7 @@ extern BOOL __objc_responds_to(id, SEL); } /** - * Returns the receiver + * Returns the receiver. */ + (id) autorelease { @@ -82,7 +87,7 @@ extern BOOL __objc_responds_to(id, SEL); } /** - * Returns the receiver + * Returns the receiver. */ + (Class) class { @@ -186,7 +191,7 @@ extern BOOL __objc_responds_to(id, SEL); } /** - * Returns the superclass of the receiver + * Returns the superclass of the receiver. */ + (Class) superclass { @@ -271,7 +276,7 @@ extern BOOL __objc_responds_to(id, SEL); } /** - * Raises an NSInvalidArgumentException + * Raises an NSInvalidArgumentException. */ - (void) forwardInvocation: (NSInvocation*)anInvocation { @@ -300,7 +305,7 @@ extern BOOL __objc_responds_to(id, SEL); } /** - * Tests for pointer equality with anObject + * Tests for pointer equality with anObject. */ - (BOOL) isEqual: (id)anObject { @@ -350,7 +355,7 @@ extern BOOL __objc_responds_to(id, SEL); } /** - * Returns YES + * Returns YES. */ - (BOOL) isProxy { @@ -536,7 +541,7 @@ extern BOOL __objc_responds_to(id, SEL); } /** - * Returns the superclass of the receivers class. + * Returns the superclass of the receiver's class. */ - (Class) superclass { diff --git a/Source/NSRunLoop.m b/Source/NSRunLoop.m index 87bf544e1..ba589770b 100644 --- a/Source/NSRunLoop.m +++ b/Source/NSRunLoop.m @@ -1181,7 +1181,7 @@ static void setPollfd(int fd, int event, GSRunLoopCtxt *ctxt) @implementation NSObject (TimedPerformers) -/** +/* * Cancels any perform operations set up for the specified target * in the current run loop. */ @@ -1210,7 +1210,7 @@ static void setPollfd(int fd, int event, GSRunLoopCtxt *ctxt) } } -/** +/* * Cancels any perform operations set up for the specified target * in the current loop, but only if the value of aSelector and argument * with which the performs were set up match those supplied.
@@ -1589,6 +1589,23 @@ static void setPollfd(int fd, int event, GSRunLoopCtxt *ctxt) +/** + *

NSRunLoop instances handle various utility tasks that must + * be performed repetitively in an application, such as processing input + * events, listening for distributed objects communications, firing + * [NSTimer]s, and sending notifications and other messages + * asynchronously.

+ * + *

In general, there is one run loop per thread in an application, which + * may always be obtained through the +currentRunLoop method, + * however unless you are using the AppKit and the [NSApplication] class, the + * run loop will not be started unless you explicitly send it a + * -run message.

+ * + *

At any given point, a run loop operates in a single mode, usually + * NSDefaultRunLoopMode. Other options include + * NSConnectionReplyMode, and certain modes used by the AppKit.

+ */ @implementation NSRunLoop + (void) initialize @@ -1607,6 +1624,9 @@ static void setPollfd(int fd, int event, GSRunLoopCtxt *ctxt) } } +/** + * Returns the run loop instance for the current thread. + */ + (NSRunLoop*) currentRunLoop { extern NSRunLoop *GSRunLoopForThread(); @@ -2038,11 +2058,21 @@ static void setPollfd(int fd, int event, GSRunLoopCtxt *ctxt) return YES; } +/** + * Runs the loop in NSDefaultRunLoopMode by repeated calls to + * -runMode:beforeDate: while there are still input sources. Exits when no + * more input sources remain. + */ - (void) run { [self runUntilDate: theFuture]; } +/** + * Runs the loop in NSDefaultRunLoopMode by repeated calls to + * -runMode:beforeDate: while there are still input sources. Exits when no + * more input sources remain, or date is reached, whichever occurs first. + */ - (void) runUntilDate: (NSDate*)date { double ti = [date timeIntervalSinceNow]; @@ -2061,8 +2091,15 @@ static void setPollfd(int fd, int event, GSRunLoopCtxt *ctxt) +/** + * OpenStep-compatibility methods for [NSRunLoop]. These methods are also + * all in OS X. + */ @implementation NSRunLoop (OPENSTEP) +/** + * Adds port to be monitored in given mode. + */ - (void) addPort: (NSPort*)port forMode: (NSString*)mode { @@ -2146,6 +2183,10 @@ static void setPollfd(int fd, int event, GSRunLoopCtxt *ctxt) NSEndMapTableEnumeration(&enumerator); } +/** + * Configure event processing for acting as a server process for distributed + * objects. (In the current implementation this is a no-op.) + */ - (void) configureAsServer { /* Nothing to do here */ @@ -2218,6 +2259,10 @@ static void setPollfd(int fd, int event, GSRunLoopCtxt *ctxt) } } +/** + * Removes port to be monitored from given mode. + * Ports are also removed if they are detected to be invalid. + */ - (void) removePort: (NSPort*)port forMode: (NSString*)mode { diff --git a/Source/NSScanner.m b/Source/NSScanner.m index 660897f49..075ba1862 100644 --- a/Source/NSScanner.m +++ b/Source/NSScanner.m @@ -52,9 +52,9 @@ /** *

- * The NSScanner class cluster (currently a single class in GNUstep) - * provides a mechanism to parse the contents of a string into number - * and string values by making a sequence of scan operations to + * The NSScanner class cluster (currently a single class in + * GNUstep) provides a mechanism to parse the contents of a string into + * number and string values by making a sequence of scan operations to * step through the string retrieving successive items. *

*

diff --git a/Source/NSSet.m b/Source/NSSet.m index 7124295e0..4afd774a9 100644 --- a/Source/NSSet.m +++ b/Source/NSSet.m @@ -40,7 +40,12 @@ @class GSSet; @class GSMutableSet; -@implementation NSSet +/** + * NSSet maintains an unordered collection of unique objects + * (according to [NSObject -isEqual]). When a duplicate object is added + * to the set, it replaces its old copy. + */ +@implementation NSSet static Class NSSet_abstract_class; static Class NSMutableSet_abstract_class; @@ -70,23 +75,35 @@ static Class NSMutableSet_concrete_class; } } +/** + * New autoreleased empty set. + */ + (id) set { return AUTORELEASE([[self allocWithZone: NSDefaultMallocZone()] init]); } +/** + * New set containing (unique elements of) objects. + */ + (id) setWithArray: (NSArray*)objects { return AUTORELEASE([[self allocWithZone: NSDefaultMallocZone()] initWithArray: objects]); } +/** + * New set containing single object anObject. + */ + (id) setWithObject: anObject { return AUTORELEASE([[self allocWithZone: NSDefaultMallocZone()] initWithObjects: &anObject count: 1]); } +/** + * New set containing (unique elements of) objects. + */ + (id) setWithObjects: (id*)objects count: (unsigned)count { @@ -94,6 +111,9 @@ static Class NSMutableSet_concrete_class; initWithObjects: objects count: count]); } +/** + * New set with objects in given nil-terminated list. + */ + (id) setWithObjects: firstObject, ... { id set; @@ -104,6 +124,9 @@ static Class NSMutableSet_concrete_class; return AUTORELEASE(set); } +/** + * Copy constructor. + */ + (id) setWithSet: (NSSet*)aSet { return AUTORELEASE([[self allocWithZone: NSDefaultMallocZone()] @@ -248,7 +271,9 @@ static Class NSMutableSet_concrete_class; return self; } -/* +/** + * Initialize to contain (unique elements of) objects. + * */ - (id) initWithObjects: (id*)objects count: (unsigned)count @@ -257,6 +282,9 @@ static Class NSMutableSet_concrete_class; return 0; } +/** + * If anObject is in set, return it (the copy in the set). + */ - (id) member: (id)anObject { return [self subclassResponsibility: _cmd]; @@ -277,11 +305,17 @@ static Class NSMutableSet_concrete_class; return [copy initWithSet: self copyItems: NO]; } +/** + * Return enumerator over objects in set. Order is undefined. + */ - (NSEnumerator*) objectEnumerator { return [self subclassResponsibility: _cmd]; } +/** + * Initialize with (unique elements of) objects in given nil-terminated list. + */ - (id) initWithObjects: firstObject, ... { GS_USEIDLIST(firstObject, @@ -343,11 +377,17 @@ static Class NSMutableSet_concrete_class; return self; } +/** + * Initialize with same items as other (items not copied). + */ - (id) initWithSet: (NSSet*)other { return [self initWithSet: other copyItems: NO]; } +/** + * Return array of all objects in set. Order is undefined. + */ - (NSArray*) allObjects { id e = [self objectEnumerator]; @@ -362,6 +402,9 @@ static Class NSMutableSet_concrete_class; initWithObjects: k count: c]); } +/** + * Return an arbitrary object from set, or nil if this is empty set. + */ - (id) anyObject { if ([self count] == 0) @@ -373,6 +416,10 @@ static Class NSMutableSet_concrete_class; } } +/** + * Return whether set contains an object equal to this one according + * to [NSObject -isEqual:]. + */ - (BOOL) containsObject: (id)anObject { return (([self member: anObject]) ? YES : NO); @@ -383,6 +430,10 @@ static Class NSMutableSet_concrete_class; return [self count]; } +/** + * Send each object given message (with no arguments). + * Identical to [-makeObjectsPerformSelector:]. + */ - (void) makeObjectsPerform: (SEL)aSelector { id o, e = [self objectEnumerator]; @@ -391,6 +442,10 @@ static Class NSMutableSet_concrete_class; [o performSelector: aSelector]; } +/** + * Send each object given message (with no arguments). + * Identical to [-makeObjectsPerform:]. + */ - (void) makeObjectsPerformSelector: (SEL)aSelector { id o, e = [self objectEnumerator]; @@ -399,6 +454,10 @@ static Class NSMutableSet_concrete_class; [o performSelector: aSelector]; } +/** + * Send each object given message with given argument. + * Identical to [-makeObjectsPerform:withObject:]. + */ - (void) makeObjectsPerformSelector: (SEL)aSelector withObject: argument { id o, e = [self objectEnumerator]; @@ -407,6 +466,10 @@ static Class NSMutableSet_concrete_class; [o performSelector: aSelector withObject: argument]; } +/** + * Send each object given message with given argument. + * Identical to [-makeObjectsPerformSelector:withObject:]. + */ - (void) makeObjectsPerform: (SEL)aSelector withObject: argument { id o, e = [self objectEnumerator]; @@ -415,6 +478,9 @@ static Class NSMutableSet_concrete_class; [o performSelector: aSelector withObject: argument]; } +/** + * Return whether set intersection with otherSet is non-empty. + */ - (BOOL) intersectsSet: (NSSet*) otherSet { id o = nil, e = nil; @@ -433,6 +499,9 @@ static Class NSMutableSet_concrete_class; return NO; } +/** + * Return whether subset of otherSet. + */ - (BOOL) isSubsetOfSet: (NSSet*) otherSet { id o = nil, e = nil; @@ -468,6 +537,9 @@ static Class NSMutableSet_concrete_class; return NO; } +/** + * Return whether each set is subset of the other. + */ - (BOOL) isEqualToSet: (NSSet*)other { if ([self count] != [other count]) @@ -484,11 +556,17 @@ static Class NSMutableSet_concrete_class; return YES; } +/** + * Returns listing of objects in set. + */ - (NSString*) description { return [self descriptionWithLocale: nil]; } +/** + * Returns listing of objects in set. + */ - (NSString*) descriptionWithLocale: (NSDictionary*)locale { return [[self allObjects] descriptionWithLocale: locale]; @@ -496,6 +574,10 @@ static Class NSMutableSet_concrete_class; @end + +/** + * Mutable version of [NSSet]. + */ @implementation NSMutableSet + (void) initialize @@ -505,6 +587,9 @@ static Class NSMutableSet_concrete_class; } } +/** + * New autoreleased instance with given capacity. + */ + (id) setWithCapacity: (unsigned)numItems { return AUTORELEASE([[self allocWithZone: NSDefaultMallocZone()] @@ -661,6 +746,7 @@ static Class NSMutableSet_concrete_class; } /** + * Adds all the objects from other to the receiver. */ - (void) unionSet: (NSSet*) other diff --git a/Source/NSSocketPort.m b/Source/NSSocketPort.m index 1d44fa0c3..92c920703 100644 --- a/Source/NSSocketPort.m +++ b/Source/NSSocketPort.m @@ -1977,7 +1977,7 @@ static unsigned wordAlign; header = [components objectAtIndex: 0]; /* * The Item header contains the item type and the length of the - * data in the item (excluding the item header itsself). + * data in the item (excluding the item header itself). */ hLength = [header length]; l = hLength - sizeof(GSPortItemHeader); diff --git a/Source/NSString.m b/Source/NSString.m index fe39a50f5..55f1f0a06 100644 --- a/Source/NSString.m +++ b/Source/NSString.m @@ -263,19 +263,26 @@ surrogatePairValue(unichar high, unichar low) /** *

- * NSString objects represent an immutable string of characters. - * NSString itself is an abstract class which provides factory - * methods to generate objects of unspecified subclasses. + * NSString objects represent an immutable string of Unicode 3.0 + * characters. These may be accessed individually as type + * unichar, an unsigned short.
+ * The [NSMutableString] subclass represents a modifiable string. Both are + * implemented as part of a class cluster and the instances you receive may + * actually be of unspecified concrete subclasses. *

*

- * A constant NSString can be created using the following syntax: + * A constant NSString can be created using the following syntax: * @"...", where the contents of the quotes are the * string, using only ASCII characters. *

*

- * To create a concrete subclass of NSString, you must have your - * class inherit from NSString and override at least the two - * primitive methods - length and characterAtIndex: + * A variable string can be created using a C printf-like format, + * as in [NSString stringWithFormat: @"Total is %f", t]. + *

+ *

+ * To create a concrete subclass of NSString, you must have your + * class inherit from NSString and override at least the two + * primitive methods - -length and -characterAtIndex: *

*

* In general the rule is that your subclass must override any @@ -286,6 +293,8 @@ surrogatePairValue(unichar high, unichar low) *

*/ @implementation NSString +// NSString itself is an abstract class which provides factory +// methods to generate objects of unspecified subclasses. static NSStringEncoding _DefaultStringEncoding; static BOOL _ByteEncodingOk; @@ -480,11 +489,17 @@ handle_printf_atsign (FILE *stream, // Creating Temporary Strings +/** + * Create an empty string. + */ + (id) string { return AUTORELEASE([[self allocWithZone: NSDefaultMallocZone()] init]); } +/** + * Create a copy of aString. + */ + (id) stringWithString: (NSString*)aString { NSString *obj; @@ -494,6 +509,9 @@ handle_printf_atsign (FILE *stream, return AUTORELEASE(obj); } +/** + * Create a string of unicode characters. + */ + (id) stringWithCharacters: (const unichar*)chars length: (unsigned int)length { @@ -504,6 +522,11 @@ handle_printf_atsign (FILE *stream, return AUTORELEASE(obj); } +/** + * Create a string based on the given C (char[]) string, which should be + * null-terminated and encoded in the default C string encoding. (Characters + * will be converted to unicode representation internally.) + */ + (id) stringWithCString: (const char*) byteString { NSString *obj; @@ -514,6 +537,11 @@ handle_printf_atsign (FILE *stream, return AUTORELEASE(obj); } +/** + * Create a string based on the given C (char[]) string, which may contain + * null bytes and should be encoded in the default C string encoding. + * (Characters will be converted to unicode representation internally.) + */ + (id) stringWithCString: (const char*)byteString length: (unsigned int)length { @@ -524,6 +552,9 @@ handle_printf_atsign (FILE *stream, return AUTORELEASE(obj); } +/** + * Create a string based on the given UTF-8 string, null-terminated. + */ + (id) stringWithUTF8String: (const char *)bytes { NSString *obj; @@ -533,6 +564,11 @@ handle_printf_atsign (FILE *stream, return AUTORELEASE(obj); } +/** + * Load contents of file at path into a new string. Will interpret file as + * containing direct unicode if it begins with the unicode byte order mark, + * else converts to unicode using default C string encoding. + */ + (id) stringWithContentsOfFile: (NSString *)path { NSString *obj; @@ -542,6 +578,11 @@ handle_printf_atsign (FILE *stream, return AUTORELEASE(obj); } +/** + * Load contents of given URL into a new string. Will interpret contents as + * containing direct unicode if it begins with the unicode byte order mark, + * else converts to unicode using default C string encoding. + */ + (id) stringWithContentsOfURL: (NSURL *)url { NSString *obj; @@ -551,6 +592,11 @@ handle_printf_atsign (FILE *stream, return AUTORELEASE(obj); } +/** + * Creates a new string using C printf-style formatting. First argument should + * be a constant format string, like '@"float val = %f"', remaining + * arguments should be the variables to print the values of, comma-separated. + */ + (id) stringWithFormat: (NSString*)format,... { va_list ap; @@ -908,9 +954,12 @@ handle_printf_atsign (FILE *stream, } /** - * This is the most basic initialiser for unicode strings. + *

Initialize with given unicode chars up to length, regardless of presence + * of null bytes. Does not copy the string. If flag, frees its storage when + * this instance is deallocated.

+ *

Note, this is the most basic initialiser for unicode strings. * In the GNUstep implementation, your subclasses may override - * this initialiser in order to have all others function. + * this initialiser in order to have all others function.

*/ - (id) initWithCharactersNoCopy: (unichar*)chars length: (unsigned int)length @@ -920,6 +969,10 @@ handle_printf_atsign (FILE *stream, return self; } +/** + *

Initialize with given unicode chars up to length, regardless of presence + * of null bytes. Copies the string and frees copy when deallocated.

+ */ - (id) initWithCharacters: (const unichar*)chars length: (unsigned int)length { @@ -977,6 +1030,12 @@ handle_printf_atsign (FILE *stream, return self; } +/** + *

Initialize with given C string byteString up to length, regardless of + * presence of null bytes. Characters converted to unicode based on the + * default C encoding. Does not copy the string. If flag, frees its storage + * when this instance is deallocated.

+ */ - (id) initWithCStringNoCopy: (char*)byteString length: (unsigned int)length freeWhenDone: (BOOL)flag @@ -1000,6 +1059,11 @@ handle_printf_atsign (FILE *stream, return self; } +/** + *

Initialize with given C string byteString up to length, regardless of + * presence of null bytes. Characters converted to unicode based on the + * default C encoding. Copies the string.

+ */ - (id) initWithCString: (const char*)byteString length: (unsigned int)length { if (length > 0) @@ -1020,12 +1084,20 @@ handle_printf_atsign (FILE *stream, return self; } +/** + *

Initialize with given C string byteString, which should be + * null-terminated. Characters are converted to unicode based on the default + * C encoding. Copies the string.

+ */ - (id) initWithCString: (const char*)byteString { return [self initWithCString: byteString length: (byteString ? strlen(byteString) : 0)]; } +/** + * Initialize to be a copy of the given string. + */ - (id) initWithString: (NSString*)string { unsigned length = [string length]; @@ -1048,6 +1120,9 @@ handle_printf_atsign (FILE *stream, return self; } +/** + * Initialize based on given null-terminated UTF-8 string bytes. + */ - (id) initWithUTF8String: (const char *)bytes { unsigned length = 0; @@ -1448,6 +1523,24 @@ handle_printf_atsign (FILE *stream, return self; } +/** + *

Initialises the receiver with the contents of the given URL. + *

+ *

Invokes [NSData+dataWithContentsOfURL:] to read the contents, then + * examines the data to infer its encoding type, and converts the + * data to a string using -initWithData:encoding: + *

+ *

The encoding to use is determined as follows ... if the data begins + * with the 16-bit unicode Byte Order Marker, then it is assumed to be + * unicode data in the appropriate ordering and converted as such.
+ * If it begins with a UTF8 representation of the BOM, the UTF8 encoding + * is used.
+ * Otherwise, the default C String encoding is used. + *

+ *

Releases the receiver and returns nil if the URL contents could not be + * read and converted to a string. + *

+ */ - (id) initWithContentsOfURL: (NSURL*)url { NSStringEncoding enc = _DefaultStringEncoding; @@ -1491,6 +1584,9 @@ handle_printf_atsign (FILE *stream, return self; } +/** + * Initializes as an empty string. + */ - (id) init { self = [self initWithCharactersNoCopy: (unichar*)0 @@ -1501,6 +1597,10 @@ handle_printf_atsign (FILE *stream, // Getting a String's Length +/** + * Returns the number of Unicode characters in this string, including the + * individual characters of composed character sequences, + */ - (unsigned int) length { [self subclassResponsibility: _cmd]; @@ -1509,20 +1609,34 @@ handle_printf_atsign (FILE *stream, // Accessing Characters +/** + * Returns unicode character at index. unichar is an unsigned + * short. Thus, a 16-bit character is returned. + */ - (unichar) characterAtIndex: (unsigned int)index { [self subclassResponsibility: _cmd]; return (unichar)0; } -/* Inefficient. Should be overridden */ +/** + * Returns this string as an array of 16-bit unichar (unsigned + * short) values. buffer must be preallocated and should be capable of + * holding -length shorts. + */ +// Inefficient. Should be overridden - (void) getCharacters: (unichar*)buffer { [self getCharacters: buffer range: ((NSRange){0, [self length]})]; return; } -/* Inefficient. Should be overridden */ +/** + * Returns aRange of string as an array of 16-bit unichar + * (unsigned short) values. buffer must be preallocated and should be capable + * of holding a sufficient number of shorts. + */ +// Inefficient. Should be overridden - (void) getCharacters: (unichar*)buffer range: (NSRange)aRange { @@ -1543,6 +1657,10 @@ handle_printf_atsign (FILE *stream, // Combining Strings +/** + * Constructs a new string consisting of this instance followed by the string + * specified by format. + */ - (NSString*) stringByAppendingFormat: (NSString*)format,... { va_list ap; @@ -1555,6 +1673,9 @@ handle_printf_atsign (FILE *stream, return ret; } +/** + * Constructs a new string consisting of this instance followed by the aString. + */ - (NSString*) stringByAppendingString: (NSString*)aString { unsigned len = [self length]; @@ -1572,6 +1693,14 @@ handle_printf_atsign (FILE *stream, // Dividing Strings into Substrings +/** + *

Returns an array of [NSString]s representing substrings of this string + * that are separated by separator (which itself is never returned in the + * array). If there are no occurrences of separator, the whole string is + * returned. If string begins or ends with separator, empty strings will + * be returned for those positions.

+ *

Note, use an [NSScanner] if you need more sophisticated parsing.

+ */ - (NSArray*) componentsSeparatedByString: (NSString*)separator { NSRange search; @@ -1664,6 +1793,12 @@ handle_printf_atsign (FILE *stream, // Finding Ranges of Characters and Substrings +/** + * Returns position of first character in this string that is in aSet. + * Positions start at 0. If the character is a composed character sequence, + * the range returned will contain the whole sequence, else just the character + * itself. + */ - (NSRange) rangeOfCharacterFromSet: (NSCharacterSet*)aSet { NSRange all = NSMakeRange(0, [self length]); @@ -1673,6 +1808,15 @@ handle_printf_atsign (FILE *stream, range: all]; } +/** + * Returns position of first character in this string that is in aSet. + * Positions start at 0. If the character is a composed character sequence, + * the range returned will contain the whole sequence, else just the character + * itself. mask may contain NSCaseInsensitiveSearch, + * NSLiteralSearch (don't consider alternate forms of composed + * characters equal), or NSBackwardsSearch (search from end of + * string). + */ - (NSRange) rangeOfCharacterFromSet: (NSCharacterSet*)aSet options: (unsigned int)mask { @@ -1683,6 +1827,15 @@ handle_printf_atsign (FILE *stream, range: all]; } +/** + * Returns position of first character in this string that is in aSet. + * Positions start at 0. If the character is a composed character sequence, + * the range returned will contain the whole sequence, else just the character + * itself. mask may contain NSCaseInsensitiveSearch, + * NSLiteralSearch (don't consider alternate forms of composed + * characters equal), or NSBackwardsSearch (search from end of + * string). Search only carried out within aRange. + */ - (NSRange) rangeOfCharacterFromSet: (NSCharacterSet*)aSet options: (unsigned int)mask range: (NSRange)aRange @@ -1729,8 +1882,7 @@ handle_printf_atsign (FILE *stream, } /** - * Invokes -rangeOfString:options: with the options mask - * set to zero. + * Invokes -rangeOfString:options: with no options. */ - (NSRange) rangeOfString: (NSString*)string { @@ -1770,11 +1922,14 @@ handle_printf_atsign (FILE *stream, *
* The options mask may contain the following options - * - * NSCaseInsensitiveSearch - * NSLiteralSearch - * NSBackwardsSearch - * NSAnchoredSearch + * NSCaseInsensitiveSearch + * NSLiteralSearch + * NSBackwardsSearch + * NSAnchoredSearch * + * The NSAnchoredSearch option means aString must occur at the + * beginning (or end, if NSBackwardsSearch is also given) of the + * string. Options should be OR'd together using '|'. */ - (NSRange) rangeOfString: (NSString *)aString options: (unsigned int)mask @@ -1804,6 +1959,11 @@ handle_printf_atsign (FILE *stream, // Determining Composed Character Sequences +/** + * Unicode utility method. If character at anIndex is part of a composed + * character sequence anIndex (note indices start from 0), returns the full + * range of this sequence. + */ - (NSRange) rangeOfComposedCharacterSequenceAtIndex: (unsigned int)anIndex { unsigned start; @@ -1836,11 +1996,24 @@ handle_printf_atsign (FILE *stream, // Identifying and Comparing Strings +/** + *

Compares this instance with aString. Returns + * NSOrderedAscending, NSOrderedDescending, or + * NSOrderedSame, depending on whether this instance occurs + * before or after string in lexical order, or is equal to it.

+ */ - (NSComparisonResult) compare: (NSString*)aString { return [self compare: aString options: 0]; } +/** + *

Compares this instance with aString. mask may be either + * NSCaseInsensitiveSearch or NSLiteralSearch. The + * latter requests a literal byte-by-byte comparison, which is fastest but may + * return inaccurate results in cases where two different composed character + * sequences may be used to express the same character.

+ */ - (NSComparisonResult) compare: (NSString*)aString options: (unsigned int)mask { @@ -1848,6 +2021,15 @@ handle_printf_atsign (FILE *stream, range: ((NSRange){0, [self length]})]; } +/** + *

Compares this instance with string. mask may be either + * NSCaseInsensitiveSearch or NSLiteralSearch. The + * latter requests a literal byte-by-byte comparison, which is fastest but may + * return inaccurate results in cases where two different composed character + * sequences may be used to express the same character. aRange refers + * to this instance, and should be set to 0..length to compare the whole + * string.

+ */ // xxx Should implement full POSIX.2 collate - (NSComparisonResult) compare: (NSString*)aString options: (unsigned int)mask @@ -1858,6 +2040,9 @@ handle_printf_atsign (FILE *stream, return strCompNsNs(self, aString, mask, aRange); } +/** + * Returns whether this string starts with aString. + */ - (BOOL) hasPrefix: (NSString*)aString { NSRange range; @@ -1866,6 +2051,9 @@ handle_printf_atsign (FILE *stream, return (range.length > 0) ? YES : NO; } +/** + * Returns whether this string ends with aString. + */ - (BOOL) hasSuffix: (NSString*)aString { NSRange range; @@ -1875,6 +2063,10 @@ handle_printf_atsign (FILE *stream, return (range.length > 0) ? YES : NO; } +/** + * Returns based on string comparison if anObject is an NSString, else + * uses ==. + */ - (BOOL) isEqual: (id)anObject { if (anObject == self) @@ -1896,6 +2088,10 @@ handle_printf_atsign (FILE *stream, return NO; } +/** + * Returns whether this instance is equal as a string to aString. See also + * -compare: and related methods. + */ - (BOOL) isEqualToString: (NSString*)aString { if ([self hash] != [aString hash]) @@ -1960,6 +2156,14 @@ handle_printf_atsign (FILE *stream, // Getting a Shared Prefix +/** + * Returns the largest initial portion of this instance shared with aString. + * mask may be either NSCaseInsensitiveSearch or + * NSLiteralSearch. The latter requests a literal byte-by-byte + * comparison, which is fastest but may return inaccurate results in cases + * where two different composed character sequences may be used to express + * the same character. + */ - (NSString*) commonPrefixWithString: (NSString*)aString options: (unsigned int)mask { @@ -2261,6 +2465,12 @@ handle_printf_atsign (FILE *stream, // Changing Case +/** + * Returns version of string in which each whitespace-delimited word + * is capitalized (not every letter). Conversion to capitals is done in a + * unicode-compliant manner but there may be exceptional cases where behavior + * is not what is desired. + */ // xxx There is more than this in word capitalization in Unicode, // but this will work in most cases - (NSString*) capitalizedString @@ -2365,6 +2575,7 @@ handle_printf_atsign (FILE *stream, // Storing the String +/** Returns self. */ - (NSString*) description { return self; @@ -2374,10 +2585,11 @@ handle_printf_atsign (FILE *stream, // Getting C Strings /** - * Returns a pointer to a null terminated string of 8-bit - * characters in the default encoding. The memory pointed - * to is not owned by the caller, so the caller must copy - * its contents to keep it. + * Returns a pointer to a null terminated string of 8-bit characters in the + * default encoding. The memory pointed to is not owned by the caller, so the + * caller must copy its contents to keep it. Raises an + * NSCharacterConversionException if loss of information would + * occur during conversion. (See -canBeConvertedToEncoding: .) */ - (const char*) cString { @@ -2397,6 +2609,11 @@ handle_printf_atsign (FILE *stream, return (const char*)[m bytes]; } +/** + * Returns a C string converted using the default C string encoding, which may + * result in information loss. The memory pointed to is not owned by the + * caller, so the caller must copy its contents to keep it. + */ - (const char*) lossyCString { NSData *d; @@ -2410,6 +2627,11 @@ handle_printf_atsign (FILE *stream, return (const char*)[m bytes]; } +/** + * Returns null-terminated UTF-8 version of this unicode string. The char[] + * memory comes from an autoreleased object, so it will eventually go out of + * scope. + */ - (const char *) UTF8String { NSData *d; @@ -2423,6 +2645,12 @@ handle_printf_atsign (FILE *stream, return (const char*)[m bytes]; } +/** + * Returns length of a version of this unicode string converted to bytes + * using the default C string encoding. If the conversion would result in + * information loss, the results are unpredictable. Check + * -canBeConvertedToEncoding: first. + */ - (unsigned int) cStringLength { NSData *d; @@ -2540,8 +2768,8 @@ handle_printf_atsign (FILE *stream, } /** - * Returns the strings content as a double. Skips leading whitespace.
- * Conversion is not localised (ie uses '.' as the decimal separator).
+ * Returns the string's content as a double. Skips leading whitespace.
+ * Conversion is not localised (i.e. uses '.' as the decimal separator).
* Returns 0.0 on underflow or if the string does not contain a number. */ - (double) doubleValue @@ -2557,8 +2785,8 @@ handle_printf_atsign (FILE *stream, } /** - * Returns the strings content as a double. Skips leading whitespace.
- * Conversion is not localised (ie uses '.' as the decimal separator).
+ * Returns the string's content as a float. Skips leading whitespace.
+ * Conversion is not localised (i.e. uses '.' as the decimal separator).
* Returns 0.0 on underflow or if the string does not contain a number. */ - (float) floatValue @@ -2573,6 +2801,11 @@ handle_printf_atsign (FILE *stream, return (float)d; } +/** + *

Returns the string's content as an int.
+ * Current implementation uses C library atoi(), which does not + * detect conversion errors -- use with care!

+ */ - (int) intValue { return atoi([self lossyCString]); @@ -2583,7 +2816,7 @@ handle_printf_atsign (FILE *stream, /** *

* Returns the encoding used for any method accepting a C string. - * This value is determined automatically from the programs + * This value is determined automatically from the program's * environment and cannot be changed programmatically. *

*

@@ -2632,6 +2865,10 @@ handle_printf_atsign (FILE *stream, table: nil]; } +/** + * Returns whether this string can be converted to the given string encoding + * without information loss. + */ - (BOOL) canBeConvertedToEncoding: (NSStringEncoding)encoding { id d = [self dataUsingEncoding: encoding allowLossyConversion: NO]; @@ -2639,11 +2876,19 @@ handle_printf_atsign (FILE *stream, return d != nil ? YES : NO; } +/** + * Converts string to a byte array in the given encoding, returning nil if + * this would result in information loss. + */ - (NSData*) dataUsingEncoding: (NSStringEncoding)encoding { return [self dataUsingEncoding: encoding allowLossyConversion: NO]; } +/** + * Converts string to a byte array in the given encoding. If flag is NO, + * nil would be returned if this would result in information loss. + */ - (NSData*) dataUsingEncoding: (NSStringEncoding)encoding allowLossyConversion: (BOOL)flag { @@ -2805,11 +3050,20 @@ handle_printf_atsign (FILE *stream, return nil; } + +/** + * Returns the encoding with which this string can be converted without + * information loss that would result in most efficient character access. + */ - (NSStringEncoding) fastestEncoding { return NSUnicodeStringEncoding; } +/** + * Returns the smallest encoding with which this string can be converted + * without information loss. + */ - (NSStringEncoding) smallestEncoding { return NSUnicodeStringEncoding; @@ -2818,6 +3072,16 @@ handle_printf_atsign (FILE *stream, // Manipulating File System Paths +/** + * Attempts to complete this string as a path in the filesystem by finding + * a unique completion if one exists and returning it by reference in + * outputName (which must be a non-nil pointer), or if it finds a set of + * completions they are returned by reference in outputArray, if it is non-nil. + * filterTypes can be an array of strings specifying extensions to consider; + * files without these extensions will be ignored and will not constitute + * completions. Returns 0 if no match found, else a positive number that is + * only accurate if outputArray was non-nil. + */ - (unsigned int) completePathIntoString: (NSString**)outputName caseSensitive: (BOOL)flag matchesIntoArray: (NSArray**)outputArray @@ -2889,7 +3153,13 @@ handle_printf_atsign (FILE *stream, return match_count; } -/* Return a string for passing to OS calls to handle file system objects. */ +/** + * Converts this string, which is assumed to be a path in Unix notation ('/' + * is file separator, '.' is extension separator) to a C string path expressed + * in the convention for the host operating system. This string will be + * automatically freed soon after it is returned, so copy it if you need it + * for long. + */ - (const char*) fileSystemRepresentation { static NSFileManager *fm = nil; @@ -2902,6 +3172,12 @@ handle_printf_atsign (FILE *stream, return [fm fileSystemRepresentationWithPath: self]; } +/** + * Converts this string, which is assumed to be a path in Unix notation ('/' + * is file separator, '.' is extension separator) to a C string path expressed + * in the convention for the host operating system. This string will be + * stored into buffer if it is shorter than size, otherwise NO is returned. + */ - (BOOL) getFileSystemRepresentation: (char*)buffer maxLength: (unsigned int)size { @@ -3372,6 +3648,10 @@ handle_printf_atsign (FILE *stream, } } +/** + * Replaces path string by one in which path components representing symbolic + * links have been replaced by their referents. + */ - (NSString*) stringByResolvingSymlinksInPath { #if defined(__MINGW__) @@ -3760,9 +4040,9 @@ handle_printf_atsign (FILE *stream, return s; } -/* - * Returs YES if the receiver represents an absolute path ... ie if it begins - * with a '/' or a '~'
+/** + * Returns YES if the receiver represents an absolute path ... i.e. if it + * begins with a '/' or a '~'
* Returns NO otherwise. */ - (BOOL) isAbsolutePath @@ -3865,6 +4145,9 @@ handle_printf_atsign (FILE *stream, return AUTORELEASE(r); } +/** + * Returns an autoreleased string with given format using the default locale. + */ + (NSString*) localizedStringWithFormat: (NSString*) format, ... { va_list ap; @@ -3886,6 +4169,11 @@ handle_printf_atsign (FILE *stream, return ret; } +/** + * Compares this string with aString ignoring case. Convenience for + * -compare:options:range: with the NSCaseInsensitiveSearch + * option, in the default locale. + */ - (NSComparisonResult) caseInsensitiveCompare: (NSString*)aString { return [self compare: aString @@ -3893,17 +4181,36 @@ handle_printf_atsign (FILE *stream, range: ((NSRange){0, [self length]})]; } +/** + *

Compares this instance with string, using rules in locale given by dict. + * mask may be either NSCaseInsensitiveSearch or + * NSLiteralSearch. The latter requests a literal byte-by-byte + * comparison, which is fastest but may return inaccurate results in cases + * where two different composed character sequences may be used to express + * the same character. compareRange refers to this instance, and should be + * set to 0..length to compare the whole string.

+ * + *

Returns NSOrderedAscending, NSOrderedDescending, + * or NSOrderedSame, depending on whether this instance occurs + * before or after string in lexical order, or is equal to it.

+ * + *

Warning: this implementation and others in NSString + * IGNORE the locale.

+ */ - (NSComparisonResult) compare: (NSString *)string options: (unsigned int)mask range: (NSRange)compareRange locale: (NSDictionary *)dict { - // FIXME: This does only a normal compare + // FIXME: This does only a normal compare, ignoring locale return [self compare: string options: mask range: compareRange]; } +/** + * Compares this instance with string, using rules in the default locale. + */ - (NSComparisonResult) localizedCompare: (NSString *)string { NSDictionary *dict = GSUserDefaultsDictionaryRepresentation(); @@ -3914,6 +4221,10 @@ handle_printf_atsign (FILE *stream, locale: dict]; } +/** + * Compares this instance with string, using rules in the default locale, + * ignoring case. + */ - (NSComparisonResult) localizedCaseInsensitiveCompare: (NSString *)string { NSDictionary *dict = GSUserDefaultsDictionaryRepresentation(); @@ -3924,6 +4235,13 @@ handle_printf_atsign (FILE *stream, locale: dict]; } +/** + * Writes contents out to file at filename, using the default C string encoding + * unless this would result in information loss, otherwise straight unicode. + * The 'atomically' option if set will cause the contents to be + * written to a temp file, which is then closed and renamed to filename. Thus, + * an incomplete file at filename should never result. + */ - (BOOL) writeToFile: (NSString*)filename atomically: (BOOL)useAuxiliaryFile { @@ -3936,6 +4254,13 @@ handle_printf_atsign (FILE *stream, return [d writeToFile: filename atomically: useAuxiliaryFile]; } +/** + * Writes contents out to anURL, using the default C string encoding + * unless this would result in information loss, otherwise straight unicode. + * See [NSURLHandle-writeData:] on which URL types are supported. + * The 'atomically' option is only heeded if the URL is a + * file:// URL; see -writeToFile:atomically: . + */ - (BOOL) writeToURL: (NSURL*)anURL atomically: (BOOL)atomically { id d = [self dataUsingEncoding: _DefaultStringEncoding]; @@ -4130,134 +4455,11 @@ handle_printf_atsign (FILE *stream, *

*

Both the traditional format and the XML format permit comments to be * placed in property list documents. In traditional format the - * comment notations used in ObjectiveC programming are supported, while + * comment notations used in Objective-C programming are supported, while * in XML format, the standard SGML comment sequences are used. *

- * A property list may only be one of the following classes - - * - * [NSArray] - * - * An array which is either empty or contains only property list - * objects.
- * An array is delimited by round brackets and its contents are comma - * separated (there is no comma after the last array element). - * - * ( "one", "two", "three" ) - * - * In XML format, an array is an element whose name is array - * and whose content is the array content. - * - * <array><string>one</string><string>two</string><string>three</string></array> - * - * - * [NSData] - * - * An array is represented as a series of pairs of hexadecimal characters - * (each pair representing a byte of data) enclosed in angle brackets. - * Spaces are ignored). - * - * < 54637374 696D67 > - * - * In XML format, a data object is an element whose name is - * data and whose content is a stream of base64 encoded bytes. - * - * [NSDate] - * - * Date objects were not traditionally allowed in property lists - * but were added when the XML format was intoroduced. GNUstep provides - * an extension to the traditional property list format to - * support date objects, but older code will not read - * property lists containing this extension.
- * This format consists of an asterisk follwed by the letter 'D' then a - * date/time in YYYY-MM-DD HH:MM:SS +/-ZZZZ format, all enclosed within - * angle brackets. - * - * <*D2002-03-22 11:30:00 +0100> - * - * In XML format, a date object is an element whose name is - * date and whose content is a date in the above format. - * - * <date>2002-03-22 11:30:00 +0100</date> - * - * - * [NSDictionary] - * - * A dictionary which is either empty or contains only string - * keys and property list objects.
- * A dictionary is delimited by curly brackets and its contents are - * semicolon terminated (there is a semicolon after each value). - * Each item in the dictionary is a key/value pair with an equals sign - * after the key and before the value. - * - * { - * "key1" = "value1"; - * } - * - * In XML format, a dictionary is an element whose name is - * dictionary and whose content consists of pairs of - * strings and other property list objects. - * - * <dictionary> - * <string>key1</string> - * <string>value1</string> - * </dictionary> - * - * - * [NSNumber] - * - * Number objects were not traditionally allowed in property lists - * but were added when the XML format was intoroduced. GNUstep provides - * an extension to the traditional property list format to - * support number objects, but older code will not read - * property lists containing this extension.
- * Numbers are stored in a variety of formats depending on their values. - * - * boolean ... either <*BY> for YES or - * <*BN> for NO.
- * In XML format this is either <true /> or - * <false /> - * - * integer ... <*INNN> where NNN is an - * integer.
- * In XML format this is <integer>NNN<integer> - * - * real ... <*RNNN> where NNN is a real - * number.
- * In XML format this is <real>NNN<real> - * - * - * - * [NSString] - * - * A string is either stored literally (if it contains no spaces or special - * characters), or is stored as a quoted string with special characters - * escaped where necessary.
- * Escape conventions are similar to those normally used in ObjectiveC - * programming, using a backslash followed by - - * - * \ a backslash character - * " a quote character - * b a backspace character - * n a newline character - * r a carriage return character - * t a tab character - * OOO (three octal digits) - * an arbitrary ascii character - * UXXXX (where X is a hexadecimal digit) - * a an arbitrary unicode character - * - * - * "hello world & others" - * - * In XML format, the string is simply stored in UTF8 format as the - * content of a string element, and the only character - * escapes required are those used by XML such as the - * '&lt;' markup representing a '<' character. - * - * <string>hello world &amp; others</string>" - * - * - * + *

See the documentation for [NSPropertyListSerialization] for more + * information on what a property list is.

*/ - (id) propertyList { @@ -4291,7 +4493,7 @@ handle_printf_atsign (FILE *stream, @end /** - * This is the mutable form of the NSString class. + * This is the mutable form of the [NSString] class. */ @implementation NSMutableString @@ -4309,19 +4511,28 @@ handle_printf_atsign (FILE *stream, // Creating Temporary Strings +/** + * Constructs an empty string. + */ + (NSMutableString*) string { return AUTORELEASE([[GSMutableStringClass allocWithZone: NSDefaultMallocZone()] initWithCapacity: 0]); } +/** + * Constructs an empty string with initial buffer size of capacity. + */ + (NSMutableString*) stringWithCapacity: (unsigned int)capacity { return AUTORELEASE([[GSMutableStringClass allocWithZone: NSDefaultMallocZone()] initWithCapacity: capacity]); } -/* Inefficient. */ +/** + * Create a string of unicode characters. + */ +// Inefficient implementation. + (NSString*) stringWithCharacters: (const unichar*)characters length: (unsigned int)length { @@ -4329,18 +4540,33 @@ handle_printf_atsign (FILE *stream, NSDefaultMallocZone()] initWithCharacters: characters length: length]); } +/** + * Load contents of file at path into a new string. Will interpret file as + * containing direct unicode if it begins with the unicode byte order mark, + * else converts to unicode using default C string encoding. + */ + (id) stringWithContentsOfFile: (NSString *)path { return AUTORELEASE([[GSMutableStringClass allocWithZone: NSDefaultMallocZone()] initWithContentsOfFile: path]); } +/** + * Create a string based on the given C (char[]) string, which should be + * null-terminated and encoded in the default C string encoding. (Characters + * will be converted to unicode representation internally.) + */ + (NSString*) stringWithCString: (const char*)byteString { return AUTORELEASE([[GSMutableStringClass allocWithZone: NSDefaultMallocZone()] initWithCString: byteString]); } +/** + * Create a string based on the given C (char[]) string, which may contain + * null bytes and should be encoded in the default C string encoding. + * (Characters will be converted to unicode representation internally.) + */ + (NSString*) stringWithCString: (const char*)byteString length: (unsigned int)length { @@ -4348,6 +4574,11 @@ handle_printf_atsign (FILE *stream, NSDefaultMallocZone()] initWithCString: byteString length: length]); } +/** + * Creates a new string using C printf-style formatting. First argument should + * be a constant format string, like '@"float val = %f"', remaining + * arguments should be the variables to print the values of, comma-separated. + */ + (NSString*) stringWithFormat: (NSString*)format, ... { va_list ap; @@ -4358,6 +4589,9 @@ handle_printf_atsign (FILE *stream, } // Designated initialiser +/** + * Constructs an empty string with initial buffer size of capacity. + */ - (id) initWithCapacity: (unsigned int)capacity { [self subclassResponsibility: _cmd]; @@ -4402,6 +4636,9 @@ handle_printf_atsign (FILE *stream, // Modify A String +/** + * Modifies this string by appending aString. + */ - (void) appendString: (NSString*)aString { NSRange aRange; @@ -4411,7 +4648,10 @@ handle_printf_atsign (FILE *stream, [self replaceCharactersInRange: aRange withString: aString]; } -/* Inefficient. */ +/** + * Modifies this string by appending string described by given format. + */ +// Inefficient implementation. - (void) appendFormat: (NSString*)format, ... { va_list ap; @@ -4430,17 +4670,27 @@ handle_printf_atsign (FILE *stream, return NSMutableStringClass; } +/** + * Modifies this instance by deleting specified range of characters. + */ - (void) deleteCharactersInRange: (NSRange)range { [self replaceCharactersInRange: range withString: nil]; } +/** + * Modifies this instance by inserting aString at loc. + */ - (void) insertString: (NSString*)aString atIndex: (unsigned int)loc { NSRange range = {loc, 0}; [self replaceCharactersInRange: range withString: aString]; } +/** + * Modifies this instance by deleting characters in range and then inserting + * aString at its beginning. + */ - (void) replaceCharactersInRange: (NSRange)range withString: (NSString*)aString { @@ -4509,6 +4759,9 @@ handle_printf_atsign (FILE *stream, return count; } +/** + * Modifies this instance by replacing contents with those of aString. + */ - (void) setString: (NSString*)aString { NSRange range = {0, [self length]}; diff --git a/Source/NSThread.m b/Source/NSThread.m index fc0faea08..1f355817a 100644 --- a/Source/NSThread.m +++ b/Source/NSThread.m @@ -429,7 +429,7 @@ gnustep_base_thread_callback(void) * has been carefully designed so that the internals of the base * library do not use threading (except for methods which explicitly * deal with threads of course) so that you can write applications - * without threading. Non-threaded applications re more efficient + * without threading. Non-threaded applications are more efficient * (no locking is required) and are easier to debug during development. */ @implementation NSThread @@ -471,8 +471,15 @@ gnustep_base_thread_callback(void) } /** - * Create a new thread - use this method rather than alloc-init - */ + *

Create a new thread - use this method rather than alloc-init. The new + * thread will begin executing the message given by aSelector, aTarget, and + * anArgument. This should have no return value, and must set up an + * autorelease pool if retain/release memory management is used. It should + * free this pool before it finishes execution.

+ * + *

Note, unlike in Cocoa (and perhaps OpenStep), the + * thread will not exit when the method finishes execution. You must + * call [Thread +exit] yourself (from the thread) to terminate it.

*/ + (void) detachNewThreadSelector: (SEL)aSelector toTarget: (id)aTarget withObject: (id)anArgument diff --git a/Source/NSTimeZone.m b/Source/NSTimeZone.m index 640702572..9c93b36f0 100644 --- a/Source/NSTimeZone.m +++ b/Source/NSTimeZone.m @@ -942,7 +942,7 @@ static NSMapTable *absolutes = 0; @implementation NSTimeZone /** - * DEPRICATED. + * DEPRECATED. */ + (NSDictionary*) abbreviationDictionary { @@ -1563,7 +1563,7 @@ static NSMapTable *absolutes = 0; } /** - * DEPRICATED: see NSTimeZoneDetail + * DEPRECATED: see NSTimeZoneDetail */ - (NSArray*) timeZoneDetailArray { @@ -1571,7 +1571,7 @@ static NSMapTable *absolutes = 0; } /** - * DEPRICATED: see NSTimeZoneDetail + * DEPRECATED: see NSTimeZoneDetail */ - (NSTimeZoneDetail*) timeZoneDetailForDate: (NSDate*)date { @@ -1604,7 +1604,7 @@ static NSMapTable *absolutes = 0; } /** - * DEPRICATED: Class is no longer used. + * DEPRECATED: Class is no longer used. */ - (BOOL) isDaylightSavingTimeZone { @@ -1613,7 +1613,7 @@ static NSMapTable *absolutes = 0; } /** - * DEPRICATED: Class is no longer used. + * DEPRECATED: Class is no longer used. */ - (NSString*) timeZoneAbbreviation { @@ -1621,7 +1621,7 @@ static NSMapTable *absolutes = 0; } /** - * DEPRICATED: Class is no longer used. + * DEPRECATED: Class is no longer used. */ - (int) timeZoneSecondsFromGMT { diff --git a/Source/NSTimer.m b/Source/NSTimer.m index 512d8e7fa..b856f5cf4 100644 --- a/Source/NSTimer.m +++ b/Source/NSTimer.m @@ -36,6 +36,14 @@ @class NSGDate; static Class NSDate_class; +/** + * An NSTimer provides a way to send a message at some time in + * the future, possibly repeating every time a fixed interval has passed. To + * use a timer, you can either create one that will automatically be added to + * the run loop in the current thread (using the -addTimer:forMode: method), + * or you can create it without adding it then add it to an [NSRunLoop] + * explicitly later. + */ @implementation NSTimer + (void) initialize diff --git a/Source/NSURL.m b/Source/NSURL.m index da8b32bf2..e0f7763d4 100644 --- a/Source/NSURL.m +++ b/Source/NSURL.m @@ -1607,8 +1607,9 @@ static unsigned urlAlign; /** * An informal protocol to which clients may conform if they wish to be - * notified of the progress in loading a URL for them. The default - * implementations of these methods do nothing. + * notified of the progress in loading a URL for them. NSURL conforms to + * this protocol but all methods are implemented as no-ops. See also + * the [NSURLHandleClient] protocol. */ @implementation NSObject (NSURLClient) diff --git a/Source/NSUnarchiver.m b/Source/NSUnarchiver.m index 0c9ff2d55..c1062dc2f 100644 --- a/Source/NSUnarchiver.m +++ b/Source/NSUnarchiver.m @@ -294,8 +294,8 @@ mapClassName(NSUnarchiverObjectInfo *info) @end /** - * This class reconstructs objects from an archive.
- * Re-using the archiver
+ *

This class reconstructs objects from an archive.


+ * Re-using the archiver *

* The -resetUnarchiverWithData:atIndex: method lets you re-use * the archive to decode a new data object or, in conjunction @@ -303,9 +303,9 @@ mapClassName(NSUnarchiverObjectInfo *info) * position in the archive), decode a second archive that exists * in the data object after the first one. *

- * Subclassing with different input format.
- * NSUnarchiver normally reads directly from an NSData object using - * the methods - + * Subclassing with different input format.

+ * NSUnarchiver normally reads directly from an [NSData] + * object using the methods - * * -deserializeTypeTag:andCrossRef:atCursor: * @@ -317,7 +317,7 @@ mapClassName(NSUnarchiverObjectInfo *info) * Also decode a crossreference number either to identify the * following item, or to refer to a previously encoded item. * Objects, Classes, Selectors, CStrings and Pointer items - * have crossreference encoding, other types do not. + * have crossreference encoding, other types do not.
* * [NSData-deserializeDataAt:ofObjCType:atCursor:context:] * @@ -325,18 +325,18 @@ mapClassName(NSUnarchiverObjectInfo *info) * * *

- * And uses other NSData methods to read the archive header information - * from within the method: + * NSUnarchiver normally uses other [NSData] methods to read + * the archive header information from within the method: * [-deserializeHeaderAt:version:classes:objects:pointers:] * to read a fixed size header including archiver version - * (obtained by [self systemVersion]) and crossreference + * (obtained by [self systemVersion]) and crossreference * table sizes. *

*

- * To subclass NSUnarchiver, you must implement your own versions of the - * four methods above, and override the 'directDataAccess' method to - * return NO so that the archiver knows to use your serialization - * methods rather than those in the NSData object. + * To subclass NSUnarchiver, you must implement your own + * versions of the four methods above, and override the 'directDataAccess' + * method to return NO so that the archiver knows to use your serialization + * methods rather than those in the [NSData] object. *

*/ @implementation NSUnarchiver @@ -356,6 +356,10 @@ static Class NSDataMallocClass; } } +/** + * Creates an NSUnarchiver to read from anObject and returns result of sending + * [NSCoder -decodeObject] to it. + */ + (id) unarchiveObjectWithData: (NSData*)anObject { NSUnarchiver *unarchiver; @@ -378,6 +382,10 @@ static Class NSDataMallocClass; return obj; } +/** + * Creates an NSUnarchiver to read from path and returns result of sending + * [NSCoder -decodeObject] to it. + */ + (id) unarchiveObjectWithFile: (NSString*)path { NSData *d = [NSDataMallocClass dataWithContentsOfFile: path]; @@ -406,6 +414,9 @@ static Class NSDataMallocClass; [super dealloc]; } +/** + * Set up to read objects from data buffer anObject. + */ - (id) initForReadingWithData: (NSData*)anObject { if (anObject == nil) @@ -1090,26 +1101,43 @@ static Class NSDataMallocClass; return [NSData data]; } +/** + * Returns whether have currently read through all of data buffer or file + * this unarchiver was initialized with. + */ - (BOOL) isAtEnd { return (cursor >= [data length]); } +/** + * Returns zone unarchived objects will be allocated from. + */ - (NSZone*) objectZone { return zone; } +/** + * Sets zone unarchived objects will be allocated from. + */ - (void) setObjectZone: (NSZone*)aZone { zone = aZone; } +/** + * Returns system version archive was encoded by. + */ - (unsigned) systemVersion { return version; } +/** + * Returns class name unarchivers will use to instantiate encoded objects + * when they report their class name as nameInArchive. + */ + (NSString*) classNameDecodedForArchiveClassName: (NSString*)nameInArchive { NSUnarchiverClassInfo *info = [clsDict objectForKey: nameInArchive]; @@ -1127,6 +1155,11 @@ static Class NSDataMallocClass; return nameInArchive; } +/** + * Sets class name unarchivers will use to instantiate encoded objects + * when they report their class name as nameInArchive. This can be used + * to support backwards compatibility across class name changes. + */ + (void) decodeClassName: (NSString*)nameInArchive asClassName: (NSString*)trueName { @@ -1152,6 +1185,10 @@ static Class NSDataMallocClass; } } +/** + * Returns class name this unarchiver uses to instantiate encoded objects + * when they report their class name as nameInArchive. + */ - (NSString*) classNameDecodedForArchiveClassName: (NSString*)nameInArchive { NSUnarchiverObjectInfo *info = [objDict objectForKey: nameInArchive]; @@ -1170,6 +1207,11 @@ static Class NSDataMallocClass; } +/** + * Set class name this unarchiver uses to instantiate encoded objects + * when they report their class name as nameInArchive. This can be used + * to provide backward compatibility across class name changes. + */ - (void) decodeClassName: (NSString*)nameInArchive asClassName: (NSString*)trueName { @@ -1195,6 +1237,10 @@ static Class NSDataMallocClass; } } +/** + * Set unarchiver to replace anObject with replacement whenever it is + * found decoded from the archive. + */ - (void) replaceObject: (id)anObject withObject: (id)replacement { unsigned i; @@ -1230,15 +1276,24 @@ static Class NSDataMallocClass; +/** + * Catagory for compatibility with old GNUstep encoding. + */ @implementation NSUnarchiver (GNUstep) -/* Re-using the unarchiver */ - +/** + * Return current position within archive byte array. + */ - (unsigned) cursor { return cursor; } + +/** + * Prepare for reuse of the unarchiver to unpack a new archive, specified in + * anObject, starting at pos. Reads archive header. + */ - (void) resetUnarchiverWithData: (NSData*)anObject atIndex: (unsigned)pos { @@ -1312,6 +1367,9 @@ static Class NSDataMallocClass; [objSave removeAllObjects]; } +/** + * Reads in header for GNUstep archive format. + */ - (void) deserializeHeaderAt: (unsigned*)pos version: (unsigned*)v classes: (unsigned*)c @@ -1337,6 +1395,9 @@ static Class NSDataMallocClass; } } +/** + * Returns YES. + */ - (BOOL) directDataAccess { return YES; diff --git a/Source/NSUndoManager.m b/Source/NSUndoManager.m index 5af3f8d9c..3f0697f1a 100644 --- a/Source/NSUndoManager.m +++ b/Source/NSUndoManager.m @@ -191,8 +191,16 @@ NSString *NSUndoManagerWillUndoChangeNotification = -/* - * The main part for the NSUndoManager implementation. +/** + * NSUndoManager provides a general mechanism supporting implementation of + * user action "undo" in applications. Essentially, it allows you to store + * sequences of messages and receivers that need to be invoked to undo or + * redo an action. The various methods in this class provide for grouping + * of sets of actions, execution of undo or redo actions, and tuning behavior + * parameters such as the size of the undo stack. Each application entity + * with its own editing history (e.g., a document) should have its own undo + * manager instance. Obtain an instance through a simple + * [[NSUndoManager alloc] init] message. */ @implementation NSUndoManager diff --git a/Source/externs.m b/Source/externs.m index 03d644e4a..4a294e3b9 100644 --- a/Source/externs.m +++ b/Source/externs.m @@ -73,7 +73,10 @@ NSString *NSConnectionReplyMode = @"NSConnectionReplyMode"; -/* Exception handler */ +/** + * Last-resort exception handler, a function taking an NSException and + * returning void. Set with NSSetUncaughtExceptionHandler(). + */ NSUncaughtExceptionHandler *_NSUncaughtExceptionHandler; /* NSBundle */