On May 21, 2008, at 12:37 PM, Johnny Lundy wrote:
This is just one example of that "little tidbit" that is always left
out of these references by Apple. It seems to be the <.O. for some
reason. The "tidbit" isn't some extraneous bell or whistle; it's
always something fundamental.
They can't take 2 lines instead of 1 to document the behavior of a
class method?
A lot of people have already mentioned that the memory management
semantics for these methods are the same everywhere and are described
in the conceptual documentation. I'd like to answer the obvious follow
up question: even if it is described in the concept docs, how would it
hurt to repeat it in the NSArray class method references? It is just
one more line...
The reason is that the location of the information says something very
important about its specificity or generality.
Let me use the class hierarchy as a comparison point: An NSView has
bounds and a frame and subviews. Those things are described in the
NSView documentation. An NSScrollView also has bounds and a frame and
subviews, but those aren't described in the NSScrollView
documentation. Why? Because if you just looked at the NSScrollView
docs and saw them there you could be left with the mistaken impression
that bounds/frame/subviews are specific to scroll views. If those
things were there it might make it easier to learn how to set the
frame rectangle of a scroll view when you specifically needed to use a
scroll view, but you would miss the very important lesson that _all_
views work this way. It would, in fact, take a long time and a lot of
use of various types of views to realize that - hey - these all work
the same way in important respects. Worse, until you did finally
figure that out, you'd be trying to use different views in different
ad hoc ways instead of realizing that they all shared common
functionality and ways of interacting with each other.
Re-describing all the superclass functionality in the subclass might
seem like it puts all the information in one place if you are using
the subclass, but it loses all sense of the overall design. Of what
parts are specific to the class you are looking at and what parts are
more general. And that sense of the overall design is a vastly more
important thing to learn than the specific use of any one class.
This might seem obvious in the case of views because it is a type of
abstraction that is very common in lots of languages. Now let's return
to the memory management semantics: exactly like a subclass and
superclass relationship, we don't want to re-describe the memory
management semantics in each class reference because then you'd never
learn that there are overarching rules to the design, which is a much
more important thing to learn than what specifically happens with any
one particular method. I think people new to Cocoa get into trouble
with this specific topic because in most C-like languages, the most
complicated thing about any API is the memory management semantics.
Different libraries do very different things. Pass in your own
buffers, have to free returned buffers, have to use some library-
specific free()-like return-the-memory APIs, et cetera. The memory
management style tends to be quite inconsistent and needs to be
documented everywhere because different API calls can have different
requirements. That this is _not_ the case in Cocoa is extremely
important.
Hope this helps,
- Greg
_______________________________________________
Cocoa-dev mailing list (Cocoa-dev@lists.apple.com)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
http://lists.apple.com/mailman/options/cocoa-dev/archive%40mail-archive.com
This email sent to [EMAIL PROTECTED]
