Fix documentation errors.

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

ChangeLog

@@ -1,3 +1,10 @@
+2005-06-15  Richard Frith-Macdonald <rfm@gnu.org>
+
+	* Documentation/manual/WorkingWithObjects.texi: Correct errors in
+	the summary of memory management conventions.
+	* Documentation/manual/WritingNewClasses.texi: Correct examples of
+	memory management in constructor methods.
+
 2005-06-15  Richard Frith-Macdonald <rfm@gnu.org>
 
 	* Source/GSFileHandle.m:

Documentation/manual/WorkingWithObjects.texi

@@ -427,15 +427,22 @@ The following summarizes the retain/release-related methods:
 @tab decreases the reference count of an object by 1
 @item @code{-autorelease}
 @tab decreases the reference count of an object by 1 at some stage in the future
-@item @code{-alloc}
+@item @code{+alloc} and @code{+allocWithZone:}
 @tab allocates memory for an object, and returns it with retain count of 1
-@item @code{-copy}
+@item @code{-copy, @code{-mutableCopy}, @code{copyWithZone:} and @code{-mutableCopyWithZone:}
 @tab makes a copy of an object, and returns it with retain count of 1
-@item @code{-new}
-@tab allocates memory for an object, and returns it in an autoreleased state
-(retain=1, but will be released automatically at some stage in the future)
+@item @code{-init} and any method whose name begins with @code{init}
+@tab initialises the receiver, returning the retain count unchanged.
+@code{-init} has had no effect on the reference count.
+@item @code{-new} and any method whose name begins with @code{new}
+@tab allocates memory for an object, initialises it, and returns the result.
 @item @code{-dealloc}
 @tab deallocates object immediately (regardless of value of retain count)
+@item convenience constructors
+@tab allocate memory for an object, and returns it in an autoreleased state
+(retain=1, but will be released automatically at some stage in the future).
+These constructors are class methods whose name generally begins with the
+name of the class (initial letter converted to lowercase).
 @end multitable
 
 The following are the main conventions you need to remember:
@@ -452,6 +459,15 @@ If you receive an autoreleased object, it will normally remain valid for the
 rest of the current method call and can even be returned as the result of the
 method.  If you need to store it away for future use (e.g. as an instance
 variable), you must retain it.
+
+@item
+The retain counts mentioned are guidelines only ... more sophisticated classes
+often perform caching and other tricks, so that @code{+alloc} methods may
+retain an instance from a cache and return it, and @code{-init} methods
+may release their receiver and return a different object (possibly obtained
+by retaining a cached object).  In these cases, the retain counts of the
+returned objects will obviously differ from the simple examples, but the
+ownership rules (how you should use the returned values) remain the same.
 @end itemize
 
 

Documentation/manual/WritingNewClasses.texi

@@ -89,12 +89,14 @@ Here is an example of a class interface declaration:
 @}
 
 // class methods
-+ new;
-+ newWithX: (float)x0 Y: (float)y0;
++ (id) new;
++ (id) newWithX: (float)x0 Y: (float)y0;
++ (Point*) point;
++ (Point*) pointWithX: (float)x0 Y: (float)y0;
 
 // instance methods
-- init;
-- initWithX: (float)x0 Y: (float)y0;
+- (id) init;
+- (id) initWithX: (float)x0 Y: (float)y0;
 - (float) x;  // (field accessor)
 - (float) y;
 - (void) setX: (float)newX;
@@ -234,9 +236,9 @@ instance variables, return values and arguments are statically typed:
   Point *lowerLeft;
   float sideLength;
 @}
-+ newWithLowerLeft: (Point *)lowerLeft sideLength: (float)sideLength;
++ (id) newWithLowerLeft: (Point *)lowerLeft sideLength: (float)sideLength;
 
-- initWithLowerLeft: (Point *)lowerLeft sideLength: (float)sideLength;
+- (id) initWithLowerLeft: (Point *)lowerLeft sideLength: (float)sideLength;
 
 - (Point *) lowerLeft;
 - (float) sideLength;
@@ -289,19 +291,19 @@ An implementation file contents are encapsulated between
 #import "Point.h"
 @@implementation Point
 // method implementations
-+ new
++ (id)new
 @{
   // statements ...
 @}
 
-+newWithX: (float)x Y: (float)y
++ (id)newWithX: (float)x Y: (float)y
 @{
   // statements ...
 @}
 
 // ...
 
-- (void) setY: (float)newY
+- (void)setY: (float)newY
 @{
   // statements ...
 @}
@@ -375,20 +377,42 @@ return to this concern below.
 
 Typically, a class will also provide one or more @code{initWith...} methods
 for initialization with arguments, and it may optionally also provide
-convenience class methods that act like constructors.  The general approach
+@code{+new} methods and convenience class methods that act like constructors.
+The general approach
 to implementing these is illustrated here for the @code{Point} class.
 
 @example
 + new
 @{
-  Point *point = [[self alloc] init];
-    // note "self" refers to the "Point" _class_ object!
-  return AUTORELEASE(point);
+  Point *point;
+
+  // note "self" refers to the "Point" _class_ object!
+  point = [[self allocWithZone: NSDefaultMallocZone()] init];
+  return point;
 @}
 
 + newWithX: (float)x0 Y: (float)y0
 @{
-  Point *point = [[self alloc] initWithX: x Y: y];
+  Point *point;
+
+  point = [[self allocWithZone: NSDefaultMallocZone()] initWithX: x Y: y];
+  return point;
+@}
+
++ point
+@{
+  Point *point;
+
+  // note "self" refers to the "Point" _class_ object!
+  point = [self new];
+  return AUTORELEASE(point);
+@}
+
++ pointWithX: (float)x0 Y: (float)y0
+@{
+  Point *point;
+
+  point = [self newWithX: x Y: y];
   return AUTORELEASE(point);
 @}
 
@@ -411,16 +435,22 @@ to implementing these is illustrated here for the @code{Point} class.
 @end example
 
 Notice that, first, the convenience constructors (@code{new} and
-@code{newWithX:Y:}) execute @code{[self alloc]} to begin with.  The
+@code{newWithX:Y:}) execute @code{[self allocWithZone:]} to begin with.  The
 ``@code{self}'' here refers to the @i{class} object, since it is used inside a
 @i{class} method.  Thus the effect is the same as if ``@code{[Point alloc]}''
-had been executed in external code.  Second, notice that they autorelease the
-new instance before returning it.  This is to follow the rules of memory
+had been executed in external code.  Second, notice that the other
+convenience constructors (@code{point} and @code{pointWithX:Y:})
+autorelease the new instance before returning it.
+This is to follow the rules of memory
 management discussed in @ref{Objects, earlier, Memory Management}.  Third,
 note that the @code{new..}  methods each call a corresponding @code{init...}
 method.  It is not necessary to maintain such a one to one correspondence but
 it is a common convention to have the convenience implementations rely on
-instance @code{init} methods as shown.
+instance @code{init} methods as shown.  Fourth, note that the use of
+@code{[self allocWithZone: NSDefaultMallocZone()]} rather than
+@code{[self alloc]} is generally unnecessary, but provides a slight
+efficiency gain since @code{+alloc} is implemented by calling
+@code{+allocWithZone:} on the default zone.
 
 @b{Designated Initializer}
 
@@ -488,7 +518,7 @@ written the @code{new} constructor above like this:
   self = [[self alloc] init];
     // note "self" now refers to the new instance!
   [self setX: 1.0];
-  return AUTORELEASE(self);
+  return self;
 @}
 @end example