Documentation tweaks

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

Source/NSArray.m

@@ -227,7 +227,7 @@ static SEL	rlSel;
 
 /**
  * Returns an autoreleased array from the contents of aURL.  The new array is
- * created using +allocWithZone: and initialised using the
+ * created using [NSObject+allocWithZone:] and initialised using the
  * -initWithContentsOfURL: method. See the documentation for those
  * methods for more detail.
  */
@@ -341,7 +341,7 @@ static SEL	rlSel;
 
 /**
  * Returns YES if anObject belongs to self. No otherwise.<br />
- * The -isEqual: method of anObject is used to test for equality.
+ * The [NSObject-isEqual:] method of anObject is used to test for equality.
  */
 - (BOOL) containsObject: (id)anObject
 {
@@ -495,7 +495,7 @@ static SEL	rlSel;
 
 /**
  * Returns the index of the first object found in the receiver
- * which is equal to anObject (using anObject's -isEqual: method).
+ * which is equal to anObject (using anObject's [NSObject-isEqual:] method).
  * Returns NSNotFound on failure.
  */
 - (unsigned) indexOfObject: (id)anObject
@@ -518,7 +518,7 @@ static SEL	rlSel;
 
 /**
  * Returns the index of the first object found in aRange of receiver
- * which is equal to anObject (using anObject's -isEqual: method).
+ * which is equal to anObject (using anObject's [NSObject-isEqual:] method).
  * Returns NSNotFound on failure.
  */
 - (unsigned) indexOfObject: (id)anObject inRange: (NSRange)aRange
@@ -1511,7 +1511,7 @@ compare(id elem1, id elem2, void* context)
 }
 
 /**
- * Removes all occurrences of anObject (found by the -isEqual: method
+ * Removes all occurrences of anObject (found by the [NSObject-isEqual:] method
  * of anObject) aRange in the receiver.
  */
 - (void) removeObject: (id)anObject inRange: (NSRange)aRange
@@ -1611,8 +1611,8 @@ compare(id elem1, id elem2, void* context)
 }
 
 /**
- * Removes all occurrences of anObject (found by anObject's -isEqual: method)
- * from the receiver.
+ * Removes all occurrences of anObject (found by anObject's
+ * [NSObject-isEqual:] method) from the receiver.
  */
 - (void) removeObject: (id)anObject
 {
@@ -1766,7 +1766,7 @@ compare(id elem1, id elem2, void* context)
 
 /**
  * Removes from the receiver, all the objects present in otherArray,
- * as determined by using the -isEqual: method.
+ * as determined by using the [NSObject-isEqual:] method.
  */
 - (void) removeObjectsInArray: (NSArray*)otherArray
 {

Source/NSAttributedString.m

@@ -923,7 +923,7 @@ static Class GSMutableAttributedStringClass;
   [self endEditing];
 }
 
-/**
+/** <override-subclass />
  *  Replaces substring; replacement is granted attributes equal to those of
  *  the first character of the portion replaced.
  */
@@ -942,21 +942,18 @@ static Class GSMutableAttributedStringClass;
 	    withAttributedString: attributedString];
 }
 
-//Grouping changes
-/**
+/** <override-dummy />
  *  Call before executing a collection of changes, for optimization.
  */
 - (void) beginEditing
 {
-  //Overridden by subclasses
 }
 
-/**
+/** <override-dummy />
  *  Call after executing a collection of changes, for optimization.
  */
 - (void) endEditing
 {
-  //Overridden by subclasses
 }
 
 @end //NSMutableAttributedString

Source/NSCoder.m

@@ -425,6 +425,8 @@
   [self decodeArrayOfObjCType: type count: count at: buf];
 }
 
+/** <override-dummy />
+ */
 - (void) decodeIndent
 {
 }
@@ -466,6 +468,8 @@
   [self encodeArrayOfObjCType: type count: count at: buf];
 }
 
+/** <override-dummy />
+ */
 - (void) encodeIndent
 {
 }

Source/NSConnection.m

@@ -380,7 +380,6 @@ static NSLock	*cached_proxies_gate = nil;
  *   Use [NSSocketPortNameServer+sharedInstance]
  *   for connections to remote hosts.
  * </p>
- * </p>
  * <p>
  *   If <em>host</em> is <code>nil</code> or an empty string,
  *   the host is taken to be the local machine.

Source/NSDictionary.m

@@ -1024,7 +1024,7 @@ compareIt(id o1, id o2, void* context)
  * according to the locale, and indented according to level.<br />
  * Unless locale is nil, a level of zero indents items by four spaces,
  * while a level of one indents them by a tab.<br />
- * If the keys in the dictionary respond to -compare:, the items are
+ * If the keys in the dictionary respond to [NSObject-compare:], the items are
  * listed by key in ascending order.  If not, the order in which the
  * items are listed is undefined.
  */

Source/NSFileHandle.m

@@ -726,30 +726,36 @@ NSString * const NSFileHandleOperationException
   return NSFileHandle_ssl_class;
 }
 
-/**
- * Establishes an SSL connection from the system that the handle is talking to.
+/** <override-dummy />
+ * Establishes an SSL connection from the system that the handle
+ * is talking to.<br />
+ * This is implented by an SSL handling subclass.<br />
+ * The default implementation just returns NO.
  */
 - (BOOL) sslAccept
 {
   return NO;
 }
 
-/**
- * Establishes an SSL connection to the system that the handle is talking to.
+/** <override-dummy />
+ * Establishes an SSL connection to the system that the handle
+ * is talking to.<br />
+ * This is implented by an SSL handling subclass.<br />
+ * The default implementation just returns NO.
  */
 - (BOOL) sslConnect
 {
   return NO;
 }
 
-/**
+/** <override-dummy />
  * Shuts down the SSL connection to the system that the handle is talking to.
  */
 - (void) sslDisconnect
 {
 }
 
-/**
+/** <override-dummy />
  * Sets the certificate to be used to identify this process to the server
  * at the opposite end of the network connection.
  */

Source/NSFileManager.m

@@ -348,7 +348,7 @@ static NSStringEncoding	defaultEncoding;
  */
 - (BOOL) changeCurrentDirectoryPath: (NSString*)path
 {
-  const _CHAR	*lpath = (_CCP)[self fileSystemRepresentationWithPath: path];
+  const _CHAR	*lpath = [self fileSystemRepresentationWithPath: path];
 #if defined(__MINGW32__)
   return SetCurrentDirectoryW(lpath) == TRUE ? YES : NO;
 #else
@@ -374,7 +374,7 @@ static NSStringEncoding	defaultEncoding;
     {
       return YES;
     }
-  lpath = (_CCP)[defaultManager fileSystemRepresentationWithPath: path];
+  lpath = [defaultManager fileSystemRepresentationWithPath: path];
 
 #ifndef __MINGW32__
   num = [attributes fileOwnerAccountID];
@@ -658,7 +658,7 @@ static NSStringEncoding	defaultEncoding;
 	{
 	  const _CHAR *lpath;
 
-	  lpath = (_CCP)[self fileSystemRepresentationWithPath: completePath];
+	  lpath = [self fileSystemRepresentationWithPath: completePath];
 	  if (CreateDirectoryW(lpath, 0) == FALSE)
 	    {
 	      return NO;
@@ -780,7 +780,7 @@ static NSStringEncoding	defaultEncoding;
 	       attributes: (NSDictionary*)attributes
 {
 #if	defined(__MINGW32__)
-  const _CHAR *lpath = (_CCP)[self fileSystemRepresentationWithPath: path];
+  const _CHAR *lpath = [self fileSystemRepresentationWithPath: path];
   HANDLE fh;
   DWORD	written = 0;
   DWORD	len = [contents length];
@@ -1012,8 +1012,8 @@ static NSStringEncoding	defaultEncoding;
   const _CHAR	*sourcePath;
   const _CHAR	*destPath;
 
-  sourcePath = (_CCP)[self fileSystemRepresentationWithPath: source];
-  destPath = (_CCP)[self fileSystemRepresentationWithPath: destination];
+  sourcePath = [self fileSystemRepresentationWithPath: source];
+  destPath = [self fileSystemRepresentationWithPath: destination];
 
   if ([self fileExistsAtPath: destination] == YES)
     {
@@ -1204,7 +1204,7 @@ static NSStringEncoding	defaultEncoding;
 
   [self _sendToHandler: handler willProcessPath: path];
 
-  lpath = (_CCP)[self fileSystemRepresentationWithPath: path];
+  lpath = [self fileSystemRepresentationWithPath: path];
   if (lpath == 0 || *lpath == 0)
     {
       return NO;
@@ -1279,7 +1279,7 @@ static NSStringEncoding	defaultEncoding;
 	    }
 	}
 
-      if (_RMDIR((_CCP)[self fileSystemRepresentationWithPath: path]) < 0)
+      if (_RMDIR([self fileSystemRepresentationWithPath: path]) < 0)
 	{
 	  return [self _proceedAccordingToHandler: handler
 	    forError: [NSString stringWithCString: GSLastErrorStr (errno)]
@@ -1308,7 +1308,7 @@ static NSStringEncoding	defaultEncoding;
  */
 - (BOOL) fileExistsAtPath: (NSString*)path isDirectory: (BOOL*)isDirectory
 {
-  const _CHAR *lpath = (_CCP)[self fileSystemRepresentationWithPath: path];
+  const _CHAR *lpath = [self fileSystemRepresentationWithPath: path];
 
   if (isDirectory != 0)
     {
@@ -1367,7 +1367,7 @@ static NSStringEncoding	defaultEncoding;
  */
 - (BOOL) isReadableFileAtPath: (NSString*)path
 {
-  const _CHAR* lpath = (_CCP)[self fileSystemRepresentationWithPath: path];
+  const _CHAR* lpath = [self fileSystemRepresentationWithPath: path];
 
   if (lpath == 0 || *lpath == _NUL)
     {
@@ -1403,7 +1403,7 @@ static NSStringEncoding	defaultEncoding;
  */
 - (BOOL) isWritableFileAtPath: (NSString*)path
 {
-  const _CHAR* lpath = (_CCP)[self fileSystemRepresentationWithPath: path];
+  const _CHAR* lpath = [self fileSystemRepresentationWithPath: path];
 
   if (lpath == 0 || *lpath == _NUL)
     {
@@ -1444,7 +1444,7 @@ static NSStringEncoding	defaultEncoding;
  */
 - (BOOL) isExecutableFileAtPath: (NSString*)path
 {
-  const _CHAR* lpath = (_CCP)[self fileSystemRepresentationWithPath: path];
+  const _CHAR* lpath = [self fileSystemRepresentationWithPath: path];
 
   if (lpath == 0 || *lpath == _NUL)
     {
@@ -1490,7 +1490,7 @@ static NSStringEncoding	defaultEncoding;
  */
 - (BOOL) isDeletableFileAtPath: (NSString*)path
 {
-  const _CHAR* lpath = (_CCP)[self fileSystemRepresentationWithPath: path];
+  const _CHAR* lpath = [self fileSystemRepresentationWithPath: path];
 
   if (lpath == 0 || *lpath == _NUL)
     {
@@ -1607,7 +1607,7 @@ static NSStringEncoding	defaultEncoding;
   NSDictionary	*d;
 
   d = [GSAttrDictionary attributesAt:
-    (_CCP)[self fileSystemRepresentationWithPath: path] traverseLink: flag];
+    [self fileSystemRepresentationWithPath: path] traverseLink: flag];
   return d;
 }
 
@@ -1641,7 +1641,7 @@ static NSStringEncoding	defaultEncoding;
   };
   DWORD SectorsPerCluster, BytesPerSector, NumberFreeClusters;
   DWORD TotalNumberClusters;
-  const _CHAR *lpath = (_CCP)[self fileSystemRepresentationWithPath: path];
+  const _CHAR *lpath = [self fileSystemRepresentationWithPath: path];
 
   if (!GetDiskFreeSpaceW(lpath, &SectorsPerCluster,
     &BytesPerSector, &NumberFreeClusters, &TotalNumberClusters))
@@ -1872,8 +1872,8 @@ static NSStringEncoding	defaultEncoding;
 #endif
 }
 
-#if	defined(__MINGW__)
-- (const unichar*) fileSystemRepresentationWithPath: (NSString*)path
+#if	defined(__MINGW32__)
+- (const GSNativeChar*) fileSystemRepresentationWithPath: (NSString*)path
 {
   NSRange	r;
 
@@ -1882,19 +1882,21 @@ static NSStringEncoding	defaultEncoding;
     {
       path = [path stringByReplacingString: @"/" withString: @"\\"];
     }
-  return (const unichar*)[path cStringUsingEncoding: NSUnicodeStringEncoding];
+  return
+    (const GSNativeChar*)[path cStringUsingEncoding: NSUnicodeStringEncoding];
 }
-- (NSString*) stringWithFileSystemRepresentation: (const unichar*)string
+- (NSString*) stringWithFileSystemRepresentation: (const GSNativeChar*)string
 					  length: (unsigned int)len
 {
   return [NSString stringWithCharacters: string length: len];
 }
 #else
-- (const char*) fileSystemRepresentationWithPath: (NSString*)path
+- (const GSNativeChar*) fileSystemRepresentationWithPath: (NSString*)path
 {
-  return [path cStringUsingEncoding: defaultEncoding];
+  return
+    (const GSNativeChar*)[path cStringUsingEncoding: defaultEncoding];
 }
-- (NSString*) stringWithFileSystemRepresentation: (const char*)string
+- (NSString*) stringWithFileSystemRepresentation: (const GSNativeChar*)string
 					  length: (unsigned int)len
 {
   return AUTORELEASE([[NSString allocWithZone: NSDefaultMallocZone()]
@@ -1992,7 +1994,7 @@ inline void gsedRelease(GSEnumeratedDirectory X)
 
   _topPath = [[NSString alloc] initWithString: path];
 
-  localPath = (_CCP)[_mgr fileSystemRepresentationWithPath: path];
+  localPath = [_mgr fileSystemRepresentationWithPath: path];
   dir_pointer = _OPENDIR(localPath);
   if (dir_pointer)
     {
@@ -2148,7 +2150,7 @@ inline void gsedRelease(GSEnumeratedDirectory X)
 #endif
 #endif
 		{
-		  if (_STAT((_CCP)[_mgr fileSystemRepresentationWithPath:
+		  if (_STAT([_mgr fileSystemRepresentationWithPath:
 		    _currentFilePath], &statbuf) != 0)
 		    {
 		      break;
@@ -2159,7 +2161,7 @@ inline void gsedRelease(GSEnumeratedDirectory X)
 		  _DIR*  dir_pointer;
 
 		  dir_pointer
-		    = _OPENDIR((_CCP)[_mgr fileSystemRepresentationWithPath:
+		    = _OPENDIR([_mgr fileSystemRepresentationWithPath:
 		    _currentFilePath]);
 		  if (dir_pointer)
 		    {
@@ -2376,8 +2378,8 @@ inline void gsedRelease(GSEnumeratedDirectory X)
 	   handler: (id)handler
 {
 #if defined(__MINGW32__)
-  if (CopyFileW((_CCP)[self fileSystemRepresentationWithPath: source],
-    (_CCP)[self fileSystemRepresentationWithPath: destination], NO))
+  if (CopyFileW([self fileSystemRepresentationWithPath: source],
+    [self fileSystemRepresentationWithPath: destination], NO))
     {
       return YES;
     }

Source/NSKeyValueObserving.m

@@ -767,11 +767,15 @@ static Class classForInstance(id o)
 
 @implementation NSObject (NSKeyValueObserving)
 
+/**
+ * NOT IMPLEMENTED
+ */
 - (void) observeValueForKeyPath: (NSString*)aPath
 		       ofObject: (id)anObject
 			 change: (NSDictionary*)aChange
 		        context: (void*)aContext
 {
+  return;
 }
 
 @end

Source/NSKeyedArchiver.m

@@ -821,19 +821,29 @@ static NSDictionary *makeReference(unsigned ref)
 @end
 
 @implementation NSObject (NSKeyedArchiverDelegate)
+/** <override-dummy />
+ */
 - (void) archiver: (NSKeyedArchiver*)anArchiver didEncodeObject: (id)anObject
 {
 }
+/** <override-dummy />
+ */
 - (id) archiver: (NSKeyedArchiver*)anArchiver willEncodeObject: (id)anObject
 {
   return anObject;
 }
+/** <override-dummy />
+ */
 - (void) archiverDidFinish: (NSKeyedArchiver*)anArchiver
 {
 }
+/** <override-dummy />
+ */
 - (void) archiverWillFinish: (NSKeyedArchiver*)anArchiver
 {
 }
+/** <override-dummy />
+ */
 - (void) archiver: (NSKeyedArchiver*)anArchiver
 willReplaceObject: (id)anObject
        withObject: (id)newObject

Source/NSKeyedUnarchiver.m

@@ -796,23 +796,33 @@ static NSMapTable	globalClassMap = 0;
 @end
 
 @implementation NSObject (NSKeyedUnarchiverDelegate)
+/** <override-dummy />
+ */
 - (Class) unarchiver: (NSKeyedUnarchiver*)anUnarchiver
   cannotDecodeObjectOfClassName: (NSString*)aName
   originalClasses: (NSArray*)classNames
 {
   return nil;
 }
+/** <override-dummy />
+ */
 - (id) unarchiver: (NSKeyedUnarchiver*)anUnarchiver
   didDecodeObject: (id)anObject
 {
   return anObject;
 }
+/** <override-dummy />
+ */
 - (void) unarchiverDidFinish: (NSKeyedUnarchiver*)anUnarchiver
 {
 }
+/** <override-dummy />
+ */
 - (void) unarchiverWillFinish: (NSKeyedUnarchiver*)anUnarchiver
 {
 }
+/** <override-dummy />
+ */
 - (void) unarchiver: (NSKeyedUnarchiver*)anUnarchiver
   willReplaceObject: (id)anObject
 	 withObject: (id)newObject

Source/NSObject.m

@@ -1571,17 +1571,8 @@ GSDescriptionForClassMethod(pcl self, SEL aSel)
   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
+// - (id) replacementObjectForKeyedArchiver: (NSKeyedArchiver *)keyedArchiver
 // {
 //     return [self replacementObjectForCoder: (NSArchiver *)keyedArchiver];
 // }
@@ -1606,41 +1597,6 @@ GSDescriptionForClassMethod(pcl self, SEL aSel)
   return self;
 }
 
-/**
- * Returns the actual object to be encoded for sending over the
- * network on a Distributed Objects connection.<br />
- * The default implementation returns self if the receiver is being
- * sent <em>bycopy</em> and returns a proxy otherwise.<br />
- * Subclasses may override this method to change this behavior,
- * eg. to ensure that they are always copied.
- */
-- (id) replacementObjectForPortCoder: (NSPortCoder*)aCoder
-{
-  static Class	proxyClass = 0;
-  static IMP	proxyImp = 0;
-
-  if (proxyImp == 0)
-    {
-      proxyClass = [NSDistantObject class];
-      /*
-       * use get_imp() because NSDistantObject doesn't implement
-       * methodForSelector:
-       */
-      proxyImp = get_imp(GSObjCClass((id)proxyClass),
-	@selector(proxyWithLocal:connection:));
-    }
-
-  if ([aCoder isBycopy])
-    {
-      return self;
-    }
-  else
-    {
-      return (*proxyImp)(proxyClass, @selector(proxyWithLocal:connection:),
-	self, [aCoder connection]);
-    }
-}
-
 
 /* NSObject protocol */
 

Source/NSPortCoder.m

@@ -1960,3 +1960,50 @@ static IMP	_xRefImp;	/* Serialize a crossref.	*/
 
 @end
 
+@implementation	NSObject (NSPortCoder)
+/**
+ * Override to substitute class when an instance is being serialized by an
+ * [NSPortCoder].  Default implementation returns -classForCoder .
+ */
+- (Class) classForPortCoder
+{
+  return [self classForCoder];
+}
+
+/**
+ * Returns the actual object to be encoded for sending over the
+ * network on a Distributed Objects connection.<br />
+ * The default implementation returns self if the receiver is being
+ * sent <em>bycopy</em> and returns a proxy otherwise.<br />
+ * Subclasses may override this method to change this behavior,
+ * eg. to ensure that they are always copied.
+ */
+- (id) replacementObjectForPortCoder: (NSPortCoder*)aCoder
+{
+  static Class	proxyClass = 0;
+  static IMP	proxyImp = 0;
+
+  if (proxyImp == 0)
+    {
+      proxyClass = [NSDistantObject class];
+      /*
+       * use get_imp() because NSDistantObject doesn't implement
+       * methodForSelector:
+       */
+      proxyImp = get_imp(GSObjCClass((id)proxyClass),
+	@selector(proxyWithLocal:connection:));
+    }
+
+  if ([aCoder isBycopy])
+    {
+      return self;
+    }
+  else
+    {
+      return (*proxyImp)(proxyClass, @selector(proxyWithLocal:connection:),
+	self, [aCoder connection]);
+    }
+}
+
+@end
+

Source/NSPortNameServer.m

@@ -63,7 +63,7 @@
  * </p>
  * This default behavior may be altered by setting the
  * <code>NSPortIsMessagePort</code> user default to NO, in which case
- * an [NSSocketPortNaemServer] will be used as the default system name server
+ * an [NSSocketPortNameServer] will be used as the default system name server
  * and you will have to use [NSMessagePortNameServer+sharedInstance]
  * for host-local, private connections.
  */

Source/NSRunLoop.m

@@ -1269,7 +1269,7 @@ extern IMP	wRetImp;
  */
 - (void) configureAsServer
 {
-/* Nothing to do here */
+  return;	/* Nothing to do here */
 }
 
 /**

Source/NSString.m

@@ -3470,7 +3470,7 @@ handle_printf_atsign (FILE *stream,
 static NSFileManager *fm = nil;
 
 #if	defined(__MINGW32__)
-- (const unichar*) fileSystemRepresentation
+- (const GSNativeChar*) fileSystemRepresentation
 {
   if (fm == nil)
     {
@@ -3479,7 +3479,7 @@ static NSFileManager *fm = nil;
   return [fm fileSystemRepresentationWithPath: self];
 }
 
-- (BOOL) getFileSystemRepresentation: (unichar*)buffer
+- (BOOL) getFileSystemRepresentation: (GSNativeChar*)buffer
 			   maxLength: (unsigned int)size
 {
   const unichar	*ptr;
@@ -3511,7 +3511,7 @@ static NSFileManager *fm = nil;
   return YES;
 }
 #else
-- (const char*) fileSystemRepresentation
+- (const GSNativeChar*) fileSystemRepresentation
 {
   if (fm == nil)
     {
@@ -3520,7 +3520,7 @@ static NSFileManager *fm = nil;
   return [fm fileSystemRepresentationWithPath: self];
 }
 
-- (BOOL) getFileSystemRepresentation: (char*)buffer
+- (BOOL) getFileSystemRepresentation: (GSNativeChar*)buffer
 			   maxLength: (unsigned int)size
 {
   const char* ptr;