Improve documentation

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

Headers/gnustep/base/NSFileManager.h

@@ -95,12 +95,30 @@
 
 @end /* NSFileManager */
 
-
+/**
+ * An informal protocol to which handler objects should conform
+ * if they wish to deal with copy and move operations performed
+ * by NSFileManager.
+ */
 @interface NSObject (NSFileManagerHandler)
+/**
+ * When an error occurs during a copy or move operation, the file manager
+ * will send this message to the handler, and will use the return value to
+ * determine whether the operation should proceed.  If the method returns
+ * YES then the operation will proceed after the error, if it returns NO
+ * then it will be aborted.
+ */
 - (BOOL) fileManager: (NSFileManager*)fileManager
   shouldProceedAfterError: (NSDictionary*)errorDictionary;
+
+/**
+ * The file manager sends this method to the handler immediately before
+ * performing part of a directory move or copy operation.  This provides
+ * the handler object with information it can use in the event of an
+ * error, to decide whether p[rocessing should proceed after the error.
+ */
 - (void) fileManager: (NSFileManager*)fileManager
-  willProcessPath: (NSString*)path;
+     willProcessPath: (NSString*)path;
 @end
 
 

Source/NSFileManager.m

@@ -157,7 +157,7 @@
 #include <Foundation/NSPathUtilities.h>
 #include <Foundation/NSFileManager.h>
 
-/**
+/*
  * GSAttrDictionary is a private NSDictionary subclass used to
  * handle file attributes efficiently ...  using lazy evaluation
  * to ensure that we only do the minimum work necessary at any time.
@@ -172,7 +172,7 @@
 + (NSDictionary*) attributesAt: (const char*)cpath traverseLink: (BOOL)traverse;
 @end
 
-/**
+/*
  * We also need a special enumerator class to enumerate the dictionary.
  */
 @interface	GSAttrDictionaryEnumerator : NSEnumerator
@@ -772,7 +772,10 @@ static NSFileManager* defaultManager = nil;
 }
 
 /**
- * Copies the file or directory at source to destination, using handler
+ * Copies the file or directory at source to destination, using a
+ * handler object which should respond to
+ * [NSObject-fileManager:willProcessPath:] and
+ * [NSObject-fileManager:shouldProceedAfterError:] messages.
  */
 - (BOOL) copyPath: (NSString*)source
 	   toPath: (NSString*)destination
@@ -861,7 +864,10 @@ static NSFileManager* defaultManager = nil;
 }
 
 /**
- * Moves the file or directory at source to destination, using handler
+ * Moves the file or directory at source to destination, using a
+ * handler object which should respond to
+ * [NSObject-fileManager:willProcessPath:] and
+ * [NSObject-fileManager:shouldProceedAfterError:] messages.
  */
 - (BOOL) movePath: (NSString*)source
 	   toPath: (NSString*)destination 
@@ -936,7 +942,10 @@ static NSFileManager* defaultManager = nil;
 }
 
 /**
- * Links the file or directory at source to destination, using handler
+ * Links the file or directory at source to destination, using a
+ * handler object which should respond to
+ * [NSObject-fileManager:willProcessPath:] and
+ * [NSObject-fileManager:shouldProceedAfterError:] messages.
  */
 - (BOOL) linkPath: (NSString*)source
 	   toPath: (NSString*)destination
@@ -948,7 +957,10 @@ static NSFileManager* defaultManager = nil;
 }
 
 /**
- * Removes the file or directory at path, using handler
+ * Removes the file or directory at path, using a
+ * handler object which should respond to
+ * [NSObject-fileManager:willProcessPath:] and
+ * [NSObject-fileManager:shouldProceedAfterError:] messages.
  */
 - (BOOL) removeFileAtPath: (NSString*)path
 		  handler: handler