Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Erik Buck <email@hidden>
- Date: Sun, 10 Jul 2005 00:32:18 -0400
I think some folks are piling on Apple's Cocoa documentation somewhat
unfairly.
Statements like "The docs as they stand are quite unfriendly" are a
bit unreasonable if you ask me.
I fully support making Cocoa documentation as friendly as possible
even to the extent of providing documentation aimed at people coming
from other frameworks because of course we want to encourage that.
For example, HP provides HP-UX documentation targeted at developers
coming from Solaris. The documentation describes specific
differences between the things you would do with Solaris vs HP-UX
right in the HP-UX documentation.
But let's be fair here. I didn't even know a method called -
setIsVisible: existed for NSWindow. It was presumably added to
support Apple Script integration. Does it matter that I didn't
know ? Of course not. -orderOut: works well. -setIsVisible: is
probably implemented to call -orderOut:. Searching for a way to
"hide" a window is no more intuitive than searching for a way to
"order" a window off screen.
Picking on the lauded MSDN and Win 32, consider the following: http://
msdn.microsoft.com/library/default.asp?url=/library/en-us/winui/winui/
windowsuserinterface/windowing/windows/windowfeatures.asp
How is Win32 BringWindowToTop() more intuitive than Cocoa -
orderFront: especially on an MSDN page about window ORDER ? The MSDN
page that describes Window z-order (itself a term unfamiliar to
noobs) has no direct mention of how to "hide" a window. It only
directly describes closing a window. It describes the IsWindowVisible
() function but there is no SetWindowVisible() function or HideWindow
() function !
Then it gets really fun with MSDN. Even though there is no
indication in the documentation about window order that includes
hiding a window without closing it, I happen to know that the
function needed is SetWindowPos(). Following link to SetWindowPos()
even though a noob wouldn't know to do that, I find out that there is
a uFlags parameter, the sixth parameter, that can be set to
SWP_HIDEWINDOW to hide a window.
[Note I love how consistent the function naming is in Win32 :(]
Search tools would have led me to SetWindowPos() and SWP_HIDEWINDOW
fairly quickly just like a quick Apple search yields http://
developer.apple.com/documentation/Cocoa/Conceptual/WinPanel/Tasks/
OpeningClosingWindows.html "These methods HIDE a window without
closing it. The method orderOut: removes an NSWindow from the screen.
You can also set a window to be removed from the screen automatically
when its application isn’t active using setHidesOnDeactivate:. And
the isVisible method tells whether an NSWindow is on or off the
screen." [emphasis is mine.]
My point in all of this is that Apple's Cocoa documentation is at
least as good as MSDN Win32 documentation IMHO. The very same
example being used to criticize Apple's documentation is [big
surprise] much worse in Win32 and MSDN. In fact Apple's
documentation for hiding a window is REALLY GOOD!
---------------
Finally, has this ever happened to any of you when using Cocoa or are
some of you carrying baggage from other frameworks ?
"'Returns an error code' is really useless, since I then don't know
what to expect, and can't try to code explicit handlers for them -
sure I can guess the most logical ones, and probably get 90% of it
right, but then there's those nasty edge cases; those errors that
come from deep inside some private framework and filter out through a
dozen layers of abstraction..."
---------------
Really finally. Please learn how to use a search tool with
documentation. I recommend google. Note the VERY FIRST HIT: http://
www.google.com/search?client=safari&rls=en&q=NSWindow
+hide&ie=UTF-8&oe=UTF-8 You don't even have to follow the link. The
answer is in the SUMMARY provided by google.
_______________________________________________
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