Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Guy English <email@hidden>
- Date: Sat, 9 Jul 2005 02:14:12 -0400
Hey,
Uh ... setIsVisible *isn't* part of the NSWindow class - it's in a
category (NSScripting) presumably to support AppleScript clients. To
hide your window you want to call [myWindow orderOut: nil]; - which
*is* covered in the NSWindow docs ... What I will give you is that
orderIn and orderOut are oddly named if you're used to other
frameworks.
So, I my guess is, in this case, you went on a hunt for a method to
"hide" or set the visibility of your window and dug around until you
found setIsVisible in NSWindowScripting.h. If you'd read the NSWindow
docs you would have found the answer. ( or at least the answer we used
before all this new-fangled-kvc-scripting-stuff :) )
That said - NSString docs cover the NSPathUtilities category and
there's something to be said for the logic of that. From the
perspective of a client of a Cocoa object it really makes no
difference if a method is implemented in a category or not so mixing
the docs seems to make sense.
A good case in point would be NSObject -
performSelector:withObject:afterDelay: is defined in a category
declared in the NSRunLoop header. Which makes sense because the delay
aspect is controlled by the run loop. But ... it's not obvious where
someone would get that information from looking at the NSObject docs.
performSelectorOnMainThread falls in the same category. Both these
methods are very useful to people writing controller classes ( if
anyone does that anymore :) ) but aren't immediately obvious from the
way the docs are layed out. That's not really a critisism - I think
Objective-C categories present a bit of a unique challenge for doc
writers is all. :)
On 7/9/05, James Andrews <email@hidden> wrote:
> I have to agree with Raffael. It is my personal opinion that the
> Apple Developer Docs are obtrusively vague, unhelpful, incomplete and
> worse yet poorly organized.
>
> Here's a great example. (from someone who doesn't understand the
> basics).......
>
> http://developer.apple.com/documentation/Cocoa/Reference/
> ApplicationKit/ObjC_classic/Classes/NSWindow.html
>
> The docs for NSWindow class.
>
> "- (void) setIsVisible(bool)flag" is not listed on the page, but
> yet is part of the class as it is listed in Cocoa in a Nutshell, and
> I have it working in my app to hide my window.
>
> James
>
> *cough* Who is now trying to figure out the basics..... *cough*
>
>
>
> On Jul 9, 2005, at 1:32 AM, mmalcolm crawford wrote:
>
> >
> > On Jul 8, 2005, at 10:14 PM, Raffael Cavallaro wrote:
> >
> >
> >>> No, it's the API reference for Application Kit.
> >>> The authoritative reference for Cocoa is ADC Home > Reference
> >>> Library > Documentation > Cocoa.
> >>>
> >>>
> >>
> >> But that's precisely the point!
> >> ADC Home > Reference Library > Documentation > Cocoa is *not* a
> >> single, authoritative set of documentation. It is dozens of
> >> different documents, of a number of different types -API
> >> Reference, Conceptual Documentation, Sample Code, Q&As - none of
> >> which take responsibility for being complete or up to date.
> >>
> >>
> > This is simply not true.
> >
> > The whole documentation suite is intended to be up to date. If you
> > find this not to be the case, then it's a bug, and you should
> > report it -- have you reported the issue with NSSound?
> >
> > It's no longer clear exactly what you want. If you're looking for
> > a "single authoritative" set of documentation for a given
> > framework, then you can go to the API Reference:
> > <http://developer.apple.com/referencelibrary/API_Fundamentals/
> > Cocoa-api-date.html>
> >
> >
> >> I single out the API reference since it should - at least in
> >> theory - provide a *complete, authoritative, and up to date
> >> reference* for everything a developer can do using Cocoa something
> >> which is not true of the other doc types. If the API Reference
> >> became the core, then it would be scrupulously kept up to date,
> >> not have Q&As added to it without even having pointers to them.
> >>
> >>
> > And as noted, if this is not true, then it is regarded as a bug.
> > Please let me know where else the API reference is deficient. As
> > far as Cocoa is concerned, as far as I am aware the API reference
> > has 100% coverage of all new API delivered in Tiger.
> >
> >
> >> It would also have sample code embedded in it.
> >>
> >>
> > Again, it does to a reasonable and limited extent. As explained
> > before, it is rare that a single class can be used in complete
> > isolation, so the general policy decision is that more complex code
> > samples should reside in higher-level documents that aggregate
> > information across the framework or frameworks. If you find places
> > where you believe the API reference would benefit from code
> > samples, please file enhancement requests. And to reiterate once
> > more, if you feel this is the case in general, file an enhancement
> > request.
> >
> >
> >
> >> As it is, one has to consult far too many different documents to
> >> get complete, authoritative and up to date documentation for
> >> simple things.
> >>
> >>
> >
> > Again, please let me know for what other simple things lack
> > complete, authoritative and up to date documentation.
> >
> > And again it would be interesting if you could provide an outline
> > for the NSView drawRect: method.
> >
> > mmalc
> >
> > _______________________________________________
> > Do not post admin requests to the list. They will be ignored.
> > Cocoa-dev mailing list (email@hidden)
> > Help/Unsubscribe/Update your Subscription:
> >
> > This email sent to email@hidden
> >
>
> _______________________________________________
> Do not post admin requests to the list. They will be ignored.
> Cocoa-dev mailing list (email@hidden)
> Help/Unsubscribe/Update your Subscription:
>
> This email sent to email@hidden
>
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Cocoa-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden