Re: Problem with NSMutableDictionary
Re: Problem with NSMutableDictionary
- Subject: Re: Problem with NSMutableDictionary
- From: mmalc crawford <email@hidden>
- Date: Sun, 19 Aug 2007 10:54:21 -0700
On Aug 19, 2007, at 10:27 AM, Peter Duniho wrote:
(Hint: it seems that those who have reached the point where they no
longer need to consult the reference for every other line of code
they write don't see a need to improve the reference :) ).
Simply using a smiley doesn't mean that the comment isn't obnoxious.
I believe we would all like to improve the reference, but it helps if
users provide constructive feedback that an be acted upon...
However, count me in for a vote for "adding bulk to the reference".
One of the biggest headaches I've had trying to learn Objective-C
and Cocoa has been the pitiful reference material that passes for
programmer documentation.
... if you find deficits, please file enhancement requests. It's not
possible to remedy problems that aren't reported.
Every now and then I find a reference topic that has a nice
elaboration and good details on the exact behavior of an class or
message, but more often than not the reference is one or two vague
sentences that make very little sense until you find the half-dozen
other topics that are relevant, but which are not actually cross-
referenced in the topic you're looking at.
The API reference is intended solely to be a "dictionary", not an
encyclopaedia.
Typically, conceptual documentation and tutorials are listed in the
"Companion guide" field in the API reference.
Yes, I already read the memory management section of the
fundamentals guide. Yes, I've seen the description of the
convention regarding autorelease rules. And yet, it would still be
very helpful to simply go ahead and explicitly describe the
autorelease behavior of each method.
Using the phrase "autorelease behaviour" suggests you still don't
fully understand memory management.
The issue is solely one of ownership, not whether or not something is
autoreleased:
<http://developer.apple.com/documentation/Cocoa/Conceptual/MemoryMgmt/Tasks/MemoryManagementRules.html
>.
Just because something follows a standard convention, that doesn't
mean that there's no use in documenting it everywhere that it can
already be inferred.
It's not that there's *no* use, it's a trade-off.
mmalc
_______________________________________________
Cocoa-dev mailing list (email@hidden)
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:
This email sent to email@hidden