Conflict between memory management descriptions in ObjC book and official docs
cocoa, memory-management, objective-c
Solution
In general, you should look in the "most global" spot for information about anything in the Cocoa APIs. Since memory management is pervasive across the system APIs and the APIs are consistent in their implementation of the Cocoa memory management policy, you simply need to read and understand the Cocoa memory management guide.
Once understood, you can safely assume that all system APIs implement to that memory management policy unless explicitly documented otherwise.
Thus, for NSMutableArray's `addObject:` method, it would have to `retain` the object added to the array or else it would be in violation of that standard policy.
You'll see this throughout the documentation. This prevents every method's documentation from being a page or more long and it makes it obvious when the rare method or class implements something that is, for whatever reason (sometimes not so good), an exception to the rule.
In the "Basic Memory Management Rules" section of the memory management guide:
You can take ownership of an object using retain.
A received object is normally guaranteed to remain valid within the method it was received in, and that method may also safely return the object to its invoker. You use retain in two situations: (1) In the implementation of an accessor method or an init method, to take ownership of an object you want to store as a property value; and (2) To prevent an object from being invalidated as a side-effect of some other operation (as explained in “Avoid Causing Deallocation of Objects You’re Using”).
(2) is the key; an NS{Mutable}Array must `retain` any added object(s) exactly because it needs to prevent the added object(s) from being invalidated due to some side-effect. To not do so would be divergent from the above rule and, thus, would be explicitly documented.
Problem
I'm trying to learn/understand what happens and why when working with or creating various objects. (Hopefully to LEARN from the docs.) I'm reading "Programming in Objective-C 2.0" (2nd edition, by Steven Kochan). On page 408, in the first paragraph is a discussion of retain counts: Note that its reference count then goes to 2. The `addObject:` method does this automatically; if you check your documentation for the `addObject:` method, you will see this fact described there. So I read the `addObject:` docs: Inserts a given object at the end of the array. There, the description is missing, while other items, like `arrayByAddingObject:`, state it: Returns a new array that is a copy of the receiving array with a given object added to the end. Where in the reference does it indicate that `addObject:` increases the retain count? Given the presence of ARC, I should still understand what these methods are doing to avoid bugs and issues. What does ARC bring to this? (Going to read that again...)