documentation tweaks

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

ChangeLog

@@ -1,3 +1,10 @@
+2011-02-16  Richard Frith-Macdonald <rfm@gnu.org>
+
+	* Source/NSFileManager.m:
+	* Documentation/coding-standards.texi:
+	* Headers/Foundation/NSXMLParser.h:
+	Documentation tweaks.
+
 2011-02-16  Jens Ayton <jens@ayton.se>
 
 	* Source/NSPropertyList.m: Fix to support 64bit integers when parsing

Documentation/coding-standards.texi

@@ -61,6 +61,7 @@ into another language, under the above conditions for modified versions.
 * Introduction::                
 * ChangeLog Entries::           
 * Coding Style::                
+* ObjectiveC::           
 * Memory Management::           
 * Error Handling::              
 * Variable Declaration::        
@@ -120,7 +121,7 @@ was changed. It's more appropriate to put that in the source code, where
 someone can find it, or in the documentation.
 
 @c ******************************************************************
-@node Coding Style, Memory Management, ChangeLog Entries, Top
+@node Coding Style, ObjectiveC, ChangeLog Entries, Top
 @section Coding Style
 
 The point is not what style is 'better' in the abstract -- it's what
@@ -286,10 +287,35 @@ the matching lines.
 #else /* not condition */
 #endif /* condition */
 
-
 @end example
+
 @c ******************************************************************
-@node Memory Management, Error Handling, Coding Style, Top
+@node ObjectiveC, Memory Management, Coding Style, Top
+@section ObjectiveC
+
+Since GNUstep is primarily written in ObjectiveC the C language coding
+standards largely apply with modifications as specified in the previous
+section.
+
+Most code is expect to be written in traditional ObjectiveC, but classes
+implementing newer APIs designed by Apple will sometimes need to be written
+using ObjectiveC-2.0, though compatibility with old compilers should be
+maintained wherever possible, and preprocessor macros must be used to at
+least conditionally build new code without breaking old code.
+
+One ObjectiveC-2.0 feature (the dot ('.') operator) is forbidden though.
+One problem is that, while apparently simple, the actual operation of this
+feature in unusual cases is actually undefined and varies between compiler
+versions.  
+The more serious problem is that the feature is simply very bad style
+because it looks like a simple structure field access and yet the code
+is really doing something very different and much more expensive, so use
+of the feature tends to lead to performance problems, bugs, and less
+explicit/readable code.
+
+
+@c ******************************************************************
+@node Memory Management, Error Handling, ObjectiveC, Top
 @section Memory Management
 
 We encourage the use of the following macros to ease retain and release
@@ -362,6 +388,23 @@ Certainly we would consider it a bug to introduce code into the
 GNUstep libraries which stopped them compiling with one of the
 commonly used compilers.
 
+Instance variables in public APIs should generally be limited to those
+which are explicitly declared to be public and which will never change
+(we want to avoid breaking ABI between releases by changing instance
+variable layouts).  Eventually compilers supporting a non-fragile ABI
+will be available and this will no longer be an issue, but until then
+we need to deal with the fragile API instance variable problem.
+
+The standard mechanism to support this is to provide a single private
+pointer variable (void *_internal;) which will be used to point to an
+area of memory containing the actual instance variables used internally.
+The internal implementation is then free to change without any change
+to the size of instances of the class.
+
+The GNUstep-base library has a standardised set of macros for writing
+code which deals with use of an _internal pointer to instance variables
+at the same time as allowing the instance variables to be used directly
+in the class if the code is built using the non-fragile ABI.
 
 @c ******************************************************************
 @node Naming Conventions, Object Persistence, Variable Declaration, Top

Headers/Foundation/NSXMLParser.h

@@ -125,22 +125,22 @@ GS_EXPORT NSString* const NSXMLParserErrorDomain;
 /**
  * Set flag to determine whether the namespaceURI and the qualified name
  * of an element is provided in the
- * [NSObject-parser:didStartElement:namespaceURI:qualifiedName:attributes:]
- * and [NSObject-parser:didEndElement:namespaceURI:qualifiedName:] methods.
+ * [NSObject(NSXMLParserDelegateEventAdditions)-parser:didStartElement:namespaceURI:qualifiedName:attributes:]
+ * and [NSObject(NSXMLParserDelegateEventAdditions)-parser:didEndElement:namespaceURI:qualifiedName:] methods.
  */
 - (void) setShouldProcessNamespaces: (BOOL)aFlag;
 
 /**
  * Sets a flag to specify whether the parser should call the
- * [NSObject-parser:didStartMappingPrefix:toURI:] and
- * [NSObject-parser:didEndMappingPrefix:] delegate methods.
+ * [NSObject(NSXMLParserDelegateEventAdditions)-parser:didStartMappingPrefix:toURI:] and
+ * [NSObject(NSXMLParserDelegateEventAdditions)-parser:didEndMappingPrefix:] delegate methods.
  */
 - (void) setShouldReportNamespacePrefixes: (BOOL)aFlag;
 
 /**
  * Sets flag to determine if declarations of external entities are
  * reported using
- * [NSObject-parser:foundExternalEntityDeclarationWithName:publicID:systemID:]
+ * [NSObject(NSXMLParserDelegateEventAdditions)-parser:foundExternalEntityDeclarationWithName:publicID:systemID:]
  */
 - (void) setShouldResolveExternalEntities: (BOOL)aFlag;
 

Source/NSFileManager.m

@@ -1028,8 +1028,9 @@ static NSStringEncoding	defaultEncoding;
 /**
  * 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.<br />
+ * [NSObject(NSFileManagerHandler)-fileManager:willProcessPath:] and
+ * [NSObject(NSFileManagerHandler)-fileManager:shouldProceedAfterError:]
+ * messages.<br />
  * Will not copy to a destination which already exists.
  */
 - (BOOL) copyPath: (NSString*)source
@@ -1127,8 +1128,9 @@ static NSStringEncoding	defaultEncoding;
 /**
  * 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.
+ * [NSObject(NSFileManagerHandler)-fileManager:willProcessPath:] and
+ * [NSObject(NSFileManagerHandler)-fileManager:shouldProceedAfterError:]
+ * messages.
  * Will not move to a destination which already exists.<br />
  */
 - (BOOL) movePath: (NSString*)source
@@ -1212,8 +1214,9 @@ static NSStringEncoding	defaultEncoding;
 /**
  * <p>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.
+ * [NSObject(NSFileManagerHandler)-fileManager:willProcessPath:] and
+ * [NSObject(NSFileManagerHandler)-fileManager:shouldProceedAfterError:]
+ * messages.
  * </p>
  * <p>If the destination is a directory, the source path is linked
  * into that directory, otherwise the destination must not exist,
@@ -1318,8 +1321,9 @@ static NSStringEncoding	defaultEncoding;
 /**
  * Removes the file or directory at path, using a
  * handler object which should respond to
- * [NSObject-fileManager:willProcessPath:] and
- * [NSObject-fileManager:shouldProceedAfterError:] messages.
+ * [NSObject(NSFileManagerHandler)-fileManager:willProcessPath:] and
+ * [NSObject(NSFileManagerHandler)-fileManager:shouldProceedAfterError:]
+ * messages.
  */
 - (BOOL) removeFileAtPath: (NSString*)path
 		  handler: handler
@@ -1801,22 +1805,22 @@ static NSStringEncoding	defaultEncoding;
  *   use the accessor methods where they are available.
  * </p>
  * <list>
- *   <item>[NSDictionary-fileCreationDate]</item>
- *   <item>[NSDictionary-fileExtensionHidden]</item>
- *   <item>[NSDictionary-fileHFSCreatorCode]</item>
- *   <item>[NSDictionary-fileHFSTypeCode]</item>
- *   <item>[NSDictionary-fileIsAppendOnly]</item>
- *   <item>[NSDictionary-fileIsImmutable]</item>
- *   <item>[NSDictionary-fileSize]</item>
- *   <item>[NSDictionary-fileType]</item>
- *   <item>[NSDictionary-fileOwnerAccountName]</item>
- *   <item>[NSDictionary-fileOwnerAccountID]</item>
- *   <item>[NSDictionary-fileGroupOwnerAccountName]</item>
- *   <item>[NSDictionary-fileGroupOwnerAccountID]</item>
- *   <item>[NSDictionary-fileModificationDate]</item>
- *   <item>[NSDictionary-filePosixPermissions]</item>
- *   <item>[NSDictionary-fileSystemNumber]</item>
- *   <item>[NSDictionary-fileSystemFileNumber]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileCreationDate]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileExtensionHidden]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileHFSCreatorCode]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileHFSTypeCode]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileIsAppendOnly]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileIsImmutable]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileSize]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileType]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileOwnerAccountName]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileOwnerAccountID]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileGroupOwnerAccountName]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileGroupOwnerAccountID]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileModificationDate]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-filePosixPermissions]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileSystemNumber]</item>
+ *   <item>[NSDictionary(NSFileAttributes)-fileSystemFileNumber]</item>
  * </list>
  */
 - (NSDictionary*) attributesOfItemAtPath: (NSString*)path