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.
previous month february 2002 next month
MTWTFSS
        1 2 3
4 5 6 7 8 9 10
11 12 13 14 15 16 17
18 19 20 21 22 23 24
25 26 27 28      
Go to today