what's an NSZone?
-
Lots of methods require an NSZone parameter. But NSZone isn't documented
anywhere. Sure, there's a header file, but it remains unclear how you'd
ever "say" a zone (other than to ask an existing object or class for *its*
zone). It seems to me there's a piece of the documentation puzzle simply
missing. m.
--
matt neuburg, phd = <matt...>, http://www.tidbits.com/matt
pantes gar anthropoi tou eidenai oregontai phusei
Subscribe to TidBITS! It's free and smart. http://www.tidbits.com/
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
You could sort of think of a NSZone as an independent heap. Objects
allocated from the same zone should live one the same set of virtual
memory pages and thus if they are used near in time you can potentially
cause less paging. Likewise, if they are to be deallocated at the same
time you will cause less fragmentation (and thus less paging). There
are cases where this is useful, but apparently the thought at Apple is
that this isn't so useful anymore.
I say 'could' because this is what NSZone used to be -- NSZone has
been neutered in recent releases (i.e., anything post-NEXTSTEP :)
Rather than documenting that this isn't so useful anymore, they just
broke zones so that you cannot easily create a real NSZone anymore (the
zone creation call just creates a child zone of the main zone which
doesn't actually split up the allocations into different subsets of the
VM pages).
I find this interesting since Apple DOES use zones internally (in
particular, CoreGraphics creates a zone). If you look in
<objc/malloc.h> you will find something analogous to an NSZone, the
malloc_zone_t. While NSZone and malloc_zone_t do basically the same
sorts of things, they are not interchangable sadly.
It would be much nicer if Apple made NSZone and malloc_zone_t be the
same thing and actually allowed developers to build real zones. This is
very useful in some limited cases -- documentation should be used to
dissuade people from misuse, not by just taking away our toys.
I've been considering adding +allocWithMallocZone: as a category on
NSObject ... :)
-tim
On Friday, February 15, 2002, at 12:35 PM, Matt Neuburg wrote:
> Lots of methods require an NSZone parameter. But NSZone isn't documented_______________________________________________
> anywhere. Sure, there's a header file, but it remains unclear how you'd
> ever "say" a zone (other than to ask an existing object or class for
> *its*
> zone). It seems to me there's a piece of the documentation puzzle simply
> missing. m.
> --
>
> matt neuburg, phd = <matt...>, http://www.tidbits.com/matt
> pantes gar anthropoi tou eidenai oregontai phusei
> Subscribe to TidBITS! It's free and smart. http://www.tidbits.com/
> _______________________________________________
> cocoa-dev mailing list | <cocoa-dev...>
> Help/Unsubscribe/Archives:
> http://www.lists.apple.com/mailman/listinfo/cocoa-dev
> Do not post admin requests to the list. They will be ignored.
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
Am Freitag den, 15. Februar 2002, um 23:46, schrieb Timothy J. Wood:
>
> I find this interesting since Apple DOES use zones internally
> (in particular, CoreGraphics creates a zone). If you look in
> <objc/malloc.h> you will find something analogous to an NSZone,
> the malloc_zone_t. While NSZone and malloc_zone_t do basically
> the same sorts of things, they are not interchangable sadly.
>
> It would be much nicer if Apple made NSZone and malloc_zone_t be
> the same thing and actually allowed developers to build real
> zones. This is very useful in some limited cases -- documentation
> should be used to dissuade people from misuse, not by just taking
> away our toys.
>
> I've been considering adding +allocWithMallocZone: as a category
> on NSObject ... :)
>
> -tim
And then there is the CFAllocator in Corefoundation, which isn't
interchangeable with NSZone as well, but appears to be pretty much
the same idea.
Nat!
------------------------------------------------------
Some people drink deep from the fountains of life, and
some just gargle. -- DLR
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
on 02-02-15 5:46 PM, Timothy J. Wood at <tjw...> wrote:
> NSZone has
> been neutered in recent releases (i.e., anything post-NEXTSTEP :)
> Rather than documenting that this isn't so useful anymore, they just
> broke zones so that you cannot easily create a real NSZone anymore
Apple's recently revised Programming Tasks documentation about basic
architecture still says that allocating objects in the application's zone is
helpful. Is this still true? I have the impression that your comments are
addressed towards more sophisticated uses of zones.
--
Bill Cheeseman - <wjcheeseman...>
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 | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
On Friday, February 15, 2002, at 06:23 PM, Nat! wrote:
> And then there is the CFAllocator in Corefoundation, which isn't
> interchangeable with NSZone as well, but appears to be pretty much the
> same idea.
Has anyone ever noticed any speedup with use of zones in a real-world
situation, or is it just a nice idea?
We've done some performance tests and it didn't seem to make any
difference (back when zones were real). I suppose that would be doubly
true in today's world where 512Mbyte is not uncommon (no VM).
-lance
_______________________________________________
Lance Bland
System Administrator at VVI
mailto:<lance.bland...>
http://www.vvi.com
Realtime, bulk and web data reporting and visualization
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
On Friday, February 15, 2002, at 03:38 PM, Bill Cheeseman wrote:
> Apple's recently revised Programming Tasks documentation about basic
> architecture still says that allocating objects in the application's
> zone is
> helpful. Is this still true? I have the impression that your comments
> are
> addressed towards more sophisticated uses of zones.
I'm not sure what is meant by "the application's zone". This has no
meaning unless there is another zone that doesn't belong to the
application :) Really, you only get one NSZone right now, so...
-tim
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
Yes, way back in NEXTSTEP 3.x I used zones on a couple projects to
great effect. In particular, you could create a 'no free' zone that had
better allocation performance and you could destroy an entire zone at
once. This was useful since I was processing a big set of data and was
basically doing:
create a huge number of interconnected objects
do some processing
destroy all the objects
In the version that crawled my data structure at the end to free
memory a bunch of time was taking up doing this work -- but if I could
just toss the whole zone, it was _much_ faster.
The oft discussed reason that zone destruction was eliminated was the
global extra ref count table used by Cocoa (and now CoreFoundation --
although it and Cocoa presumably don't share the same table).
My answer to this is that each zone should have its own global extra
ref count table for objects contained in it (although this would have
some performance impact on naively written reference counted objects --
any of the CF and Foundation objects probably wouldn't care since they
use inline ref counts and overflow into the global table).
-tim
On Friday, February 15, 2002, at 04:02 PM, Lance Bland wrote:
> On Friday, February 15, 2002, at 06:23 PM, Nat! wrote:_______________________________________________
>
>> And then there is the CFAllocator in Corefoundation, which isn't
>> interchangeable with NSZone as well, but appears to be pretty much the
>> same idea.
>
> Has anyone ever noticed any speedup with use of zones in a real-world
> situation, or is it just a nice idea?
>
> We've done some performance tests and it didn't seem to make any
> difference (back when zones were real). I suppose that would be doubly
> true in today's world where 512Mbyte is not uncommon (no VM).
>
> -lance
>
> _______________________________________________
> Lance Bland
> System Administrator at VVI
> mailto:<lance.bland...>
> http://www.vvi.com
> Realtime, bulk and web data reporting and visualization
> _______________________________________________
> cocoa-dev mailing list | <cocoa-dev...>
> Help/Unsubscribe/Archives:
> http://www.lists.apple.com/mailman/listinfo/cocoa-dev
> Do not post admin requests to the list. They will be ignored.
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
On Friday, February 15, 2002, at 07:45 PM, Timothy J. Wood wrote:
> but if I could just toss the whole zone, it was _much_ faster.
Sounds like it could be a special case. Were you only doing processing
on memory in that zone (during your testing), or did you have to go out
of that zone to get other memory? Was the improvement mostly due to the
nature of the free() or was there computational improvement? The nature
of our apps are that all the memory was segmented into different zones
and cross referenced each other and the interactions were complex.
-lance
_______________________________________________
Lance Bland
System Administrator at VVI
mailto:<lance.bland...>
http://www.vvi.com
Realtime, bulk and web data reporting and visualization
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
On Friday, February 15, 2002, at 04:59 PM, Lance Bland wrote:
> On Friday, February 15, 2002, at 07:45 PM, Timothy J. Wood wrote:
>
>> but if I could just toss the whole zone, it was _much_ faster.
>
> Sounds like it could be a special case. Were you only doing
> processing on memory in that zone (during your testing), or did
> you have to go out of that zone to get other memory? Was the
> improvement mostly due to the nature of the free() or was there
> computational improvement? The nature of our apps are that all
> the memory was segmented into different zones and cross
> referenced each other and the interactions were complex.
What I used to do was allocate an NSZone per document (using my
own document class, before NSDocument existed), and blow away
the zone when I closed the document, after saving it out to a
file. It was a lot quicker than letting every object associated
with the document dealloc itself.
-jcr
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
The NSZone is for loading and unloading only. If you've got to load or
unload, please go to the NSZone.
NSZone's don't do anything much anymore but they were handy when you
wanted to throw away a whole lot of objects all at once.
-----Original Message-----
From: Matt Neuburg [mailto:<matt...>]
Sent: Friday, February 15, 2002 12:36 PM
To: <cocoa-dev...>
Subject: what's an NSZone?
Lots of methods require an NSZone parameter. But NSZone isn't documented
anywhere. Sure, there's a header file, but it remains unclear how you'd
ever "say" a zone (other than to ask an existing object or class for
*its*
zone). It seems to me there's a piece of the documentation puzzle simply
missing. m.
--
matt neuburg, phd = <matt...>, http://www.tidbits.com/matt
pantes gar anthropoi tou eidenai oregontai phusei
Subscribe to TidBITS! It's free and smart. http://www.tidbits.com/
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives:
http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored.
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
On Friday, February 15, 2002, at 04:59 PM, Lance Bland wrote:
> Sounds like it could be a special case. Were you only doing processing
> on memory in that zone (during your testing), or did you have to go out
> of that zone to get other memory? Was the improvement mostly due to the
> nature of the free() or was there computational improvement? The nature
> of our apps are that all the memory was segmented into different zones
> and cross referenced each other and the interactions were complex.
You could use this approach any time you want to destroy an entire
category of blocks of memory and there were no pointers to those blocks
of memory from outside of that category.
Certainly, if you have a very complex set of pointer crossings you
either need to repartition your data or just not use zones at all.
-tim
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
Todd,
>>>>>> Todd Blanchard (TB) wrote at Fri, 15 Feb 2002 17:10:07 -0800:TB> The NSZone is for loading and unloading only. If you've got to load or
TB> unload, please go to the NSZone.
TB>
TB> NSZone's don't do anything much anymore but they were handy when you
TB> wanted to throw away a whole lot of objects all at once.
Correct me if I am wrong, but I still think zones can be quite useable to
constraint heap usage to "blocks" -- instead of it being spreaded over the
whole address space -- minimizing thus both the real memory needs and
swapping needed.
---
Ondra Cada
OCSoftware: <ocs...> http://www.ocs.cz
2K Development: <o.cada...> http://www.2kdevelopment.cz
private <ondra...> http://www.ocs.cz/oc
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
on 02-02-15 7:40 PM, Timothy J. Wood at <tjw...> wrote:
> On Friday, February 15, 2002, at 03:38 PM, Bill Cheeseman wrote:
>> Apple's recently revised Programming Tasks documentation about basic
>> architecture still says that allocating objects in the application's
>> zone is
>> helpful. Is this still true? I have the impression that your comments
>> are
>> addressed towards more sophisticated uses of zones.
>
> I'm not sure what is meant by "the application's zone". This has no
> meaning unless there is another zone that doesn't belong to the
> application :) Really, you only get one NSZone right now, so...
I misremembered what I had read. The documentation says this:
"When one object creates another, it is often a good idea to make sure they
are both allocated from the same region of memory. The zone method (declared
in the NSObject protocol) can be used for this purpose; it returns the zone
where the receiver is located. For example:
"id myCompanion = [[TheClass allocWithZone:[self zone]] init];"
So, you're saying this is meaningless, because the zone now consists of all
available memory?
--
Bill Cheeseman - <wjcheeseman...>
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 | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
> What I used to do was allocate an NSZone per document (using my
> own document class, before NSDocument existed), and blow away
> the zone when I closed the document, after saving it out to a
> file. It was a lot quicker than letting every object associated
> with the document dealloc itself.
Of course, dealloc often does things besides just freeing the memory
of the object in question. Removing notification observers, getting rid
of timers... this mass-free technique using zones can certainly be
useful, but it was not without problems. I think the strategy in OS X's
malloc implementation was to make it as blindingly fast as possible, so
that alloc/free overhead largely ceased to be relevant. For *most* (but
certainly not all) applications, I think it is a success. For those
applications where you are truly allocating such a large number of small
objects that this overhead is killing you, you can always do your own
custom allocation.
And if I understand the previous messages in this thread, you can
still make your own NSZone and just throw it away; it just gets
allocated as a sub-block inside your main zone, instead of as a separate
zone. I'm not really clear on why people find that so objectionable;
that seems like an implementation detail to me. What am I missing?
Ben Haller
Stick Software
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
On Friday, February 15, 2002, at 02:46 PM, Timothy J. Wood wrote:
> You could sort of think of a NSZone as an independent heap. Objects
> allocated from the same zone should live one the same set of virtual
> memory pages and thus if they are used near in time you can potentially
> cause less paging. Likewise, if they are to be deallocated at the same
> time you will cause less fragmentation (and thus less paging). There
> are cases where this is useful, but apparently the thought at Apple is
> that this isn't so useful anymore.
It was NeXT that had that thought.
> I find this interesting since Apple DOES use zones internally (in
> particular, CoreGraphics creates a zone). If you look in
> <objc/malloc.h> you will find something analogous to an NSZone, the
> malloc_zone_t. While NSZone and malloc_zone_t do basically the same
> sorts of things, they are not interchangable sadly.
In OS releases post 10.1, they have been made interchangeable, as in
this implementation of the NSZoneMalloc() function:
void *NSZoneMalloc(NSZone *zone, unsigned size) {
if (NULL == zone) zone = (NSZone *)malloc_default_zone();
return malloc_zone_malloc((malloc_zone_t *)zone, size);
}
And it's still not a good idea to destroy a zone if any objects that
aren't yours might have gotten hold of that zone to allocate themselves
in. (Well, that sentence doesn't parse easily, but you probably
understand.)
However, the OpenStep semantics for NSRecycleZone() remain, so it does
nothing at all since there's no way to "merge" malloc_zones. You have
to drop to the malloc_zone API to destroy one.
Chris Kane
Cocoa Frameworks, Apple
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
On Friday, February 15, 2002, at 03:23 PM, Nat! wrote:
> And then there is the CFAllocator in Corefoundation, which isn't
> interchangeable with NSZone as well, but appears to be pretty much the
> same idea.
In 10.1, CFAllocators and malloc_zone_t's are bridged -- mostly
interchangeable (I think CFAllocatorSetDefault() requires its parameter
to really be a CFAllocator, which isn't too much to ask; setting a
custom zone that you're going to destroy in the future as the default
allocator would be a bad idea anyway). One can see this nastiness in
the Darwin CF sources.
Chris Kane
Cocoa Framework, Apple
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
On Fri, 15 Feb 2002 12:35:54 -0800, Matt Neuburg <matt...> said:
> Lots of methods require an NSZone parameter. But NSZone isn't documented
> anywhere. Sure, there's a header file, but it remains unclear how you'd
> ever "say" a zone (other than to ask an existing object or class for *its*
> zone). It seems to me there's a piece of the documentation puzzle simply
> missing. m.
Many thanks for the interesting info on this.
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? This is a perfect
example. Since there are methods that refer to a class called NSZone, there
needs to be a document called NSZone.html. In fact, let me go further. This
scattering of the class documents in more than one place is confusing. The
AppKit / Foundation distinction is not inherently obvious to beginners.
There should be ONE folder with one NSxxx.html document per class. And
while we're at it, combine informal protocol documents with their class.
There is no reason whatever why the info on NSObject needs to be spread out
over several documents. Also, the reason I couldn't find the NSZone methods
is that they are all global functions; you have to look in
FoundationFunctions.html. This is confusing from a documentation
perspective - one more place to look when you've already tried three or
four other places, and I'm always forgetting to look there. We've got
hyperlinks here, oh mighty doc person, so couldn't we please have a few?
Why shouldn't the documentation do the organizing for us rather than
forcing us to search through everything every time?
Going beyond documentation, in fact, I'd like to question this last matter
from an object-orientation perspective. In brief: Why do global functions
exist at all? Couldn't all the zone-related functions here, for instance,
be class methods on NSZone? Maybe I'm way off the deep end here, but in an
object-oriented world my natural expectation when I want to create an
NSZone is that I would be talking to the NSZone class about this. And so on
for all such global functions. m.
--
matt neuburg, phd = <matt...>, http://www.tidbits.com/matt
pantes gar anthropoi tou eidenai oregontai phusei
Subscribe to TidBITS! It's free and smart. http://www.tidbits.com/
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
On Saturday, February 16, 2002, at 11:46 AM, Chris Kane wrote:
> In OS releases post 10.1, they have been made interchangeable, as in
> this implementation of the NSZoneMalloc() function:
Thanks! This should help OmniWeb -- we have objects that have vastly
different life times. In particular the browser history nodes need to
be in a different zone from the actual pages since otherwise we leave
little crumbs behind in the heap every time you visit a page.
Off to go investigate this.... :)
-tim
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
On Sunday, February 17, 2002, at 10:30 AM, Timothy J. Wood wrote:
> Off to go investigate this.... :)
So, like Chris' comments suggested (but I just wanted to confirm),
NSCreateZone just returns the default zone (since it needs to be
symmetric with NSRecycleZone).
Guess I'll go fix OmniWeb now... :)
-tim
/*
cc -O2 -Wall zone-test.m -o zone-test -framework Foundation
*/
#import <Foundation/Foundation.h>
#import <objc/malloc.h>
int main (int argc, char *argv[])
{
NSZone *nsZone;
nsZone = NSCreateZone(NSPageSize(), NSPageSize(), YES);
fprintf(stderr, "created NSZone = 0x%08x\n", nsZone);
fprintf(stderr, "default NSZone = 0x%08x\n", NSDefaultMallocZone());
fprintf(stderr, "default malloc zone = 0x%08x\n",
malloc_default_zone());
return 0;
}
created NSZone = 0x00084010
default NSZone = 0x00084010
default malloc zone = 0x00084010
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
on 02-02-17 12:43 PM, Matt Neuburg at <matt...> 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 - <hhickman...>
Rollie Rollefson - (oops, I can't find it)
--
Bill Cheeseman - <wjcheeseman...>
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 | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored. -
On Sun, 17 Feb 2002 14:26:54 -0500, Bill Cheeseman
<wjcheeseman...> said:
> 2. PROGRAMMING TOPICS. The Programming Topics section on the Cocoa Developer
> Documentation page got much better
I agree; my comments had nothing to do with this. Incidentally, some of the
"books" included with the documentation are brilliantly written. (And if
you know who I am, you know that I don't say that sort of thing lightly or
uncritically.) One would like to see an authorship attribution. - Okay,
this has gotten far enough off topic now. m.
--
matt neuburg, phd = <matt...>, http://www.tidbits.com/matt
pantes gar anthropoi tou eidenai oregontai phusei
Subscribe to TidBITS! It's free and smart. http://www.tidbits.com/
_______________________________________________
cocoa-dev mailing list | <cocoa-dev...>
Help/Unsubscribe/Archives: http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored.
