Re: what's an NSZone?
Re: what's an NSZone?
- Subject: Re: what's an NSZone?
- From: Bill Cheeseman <email@hidden>
- Date: Sun, 17 Feb 2002 14:26:54 -0500
on 02-02-17 12:43 PM, Matt Neuburg at email@hidden wrote:
>
Going back to my original question - isn't there someone on this list whose
>
job is to think about what's wrong with the docs?
Yes, and they've been doing a lot about it lately. Just a few observations
on some of your comments:
1. CLASS REFERENCE DOCUMENTS. I understand that there is a history of
placing the class reference document for each class in the framework folder
along with the class headers and related resources. That way, the class is
"self-documenting." So you go, say, to
/System/Library/Frameworks/AppKit.framework, then you tunnel further down
through
Versions/Current/Resources/English.lproj/Documentation/Reference/ObjC_classi
c and, Whew!, there it is, AppKit.pdf and AppKitTOC.html and related HTML
files. And the headers are nearby, which is good because sometimes the
comments in the headers reveal information that can be found nowhere else.
I really like this concept of self-documentation. But of course it's
awkward. So you can go instead to /Developer/Documentation/Cocoa/Reference
and find it all linked from one place, as you request, using aliases or
whatever.
Or, better yet, go to Cocoa Help from the PB Help menu, and there it all is,
on the Cocoa Developer Documentation page, under Reference Documentation:
Application Kit or Foundation. Click on either, and you get an alphabetical
list by class (see #3, below, regarding functions, constants and protocols).
And if you want to see whether any of it has been updated since your last
Developer Tools CD arrived, just go to the web site, which is organized
identically.
2. PROGRAMMING TOPICS. The Programming Topics section on the Cocoa Developer
Documentation page got much better in November or December, when the ongoing
project to rewrite the Cocoa documentation came to some sort of interim
fruition. Interim, since it isn't done yet. There are still some
"description forthcoming" topics, but not nearly as many as two or three
months ago. According to Apple's blurb on the What's New page for Cocoa
documentation, they got rid of over 700 of them in the December release.
A lot of general topical material that had been in some of the class
specification documents since time immemorial was pulled out and placed into
the appropriate topical document, where it belongs and is much easier to
find if you don't know your way around the Cocoa classes yet. And a lot of
it was rewritten to make it more accurate and complete.
Also, some of the legacy documentation -- for example, "Application Design
for Scripting, Documents, and Undo" -- got updated at some point and moved
into the "Program Design" topic, where its new name makes it much more
likely that newcomers will read it, as they should. I would like to see the
legacy "Tools & Techniques Book" updated, too (I've told the documentation
team so), because it has a lot of material in it about the details of
Project Builder and Interface Builder that aren't available anywhere else --
although a lot of it is of course now obsolete.
In general, I find the organization of the Programming Topics on the Cocoa
Developer Documentation page to be very useful. I almost always find what
I'm looking for right off the bat. And the internal cross-referencing with
topics, and the cross-referencing both ways between topics and class
reference documents got a LOT better in December.
3. Somebody at Apple said a little while ago that they are aware the
functions, constants and protocol reference material needs to be integrated
into the indexing of the documentation more effectively. They don't
currently show up when you do a Find on them in PB, but I understand that
the PB Gods as well as the documentation team are working on it.
4. As I say, there is an ongoing project at Apple to update this
documentation. Heather Hickman got a lot of developers to contribute
suggestions (I contributed many, and I know others did, too) and to review
"beta" drafts of the December revisions. I believe Matt Rollefson (Rollie)
is on the front lines for the project. I've seen both of them respond to
posts on this list from time to time, so I'm sure they're lurking here and
would appreciate continuing feedback.
They seem to have focused on the stuff that everybody needs to know, first,
which is the correct approach. NSZone surely doesn't fall in that category,
although it would be nice to see it documented.
Documentation feedback, like any feedback, is most helpful when it is
specific. Since they post here occasionally, I don't think I'm doing
anything untoward in mentioning their email addresses again:
Heather Hickman - email@hidden
Rollie Rollefson - (oops, I can't find it)
--
Bill Cheeseman - email@hidden
Quechee Software, Quechee, Vermont, USA
http://www.quecheesoftware.com
The AppleScript Sourcebook -
http://www.AppleScriptSourcebook.com
Vermont Recipes -
http://www.stepwise.com/Articles/VermontRecipes
Croquet Club of Vermont -
http://members.valley.net/croquetvermont
_______________________________________________
cocoa-dev mailing list | email@hidden
Help/Unsubscribe/Archives:
http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored.