Documentation frustrations
Documentation frustrations
- Subject: Documentation frustrations
- From: Bill Nalen <email@hidden>
- Date: Mon, 4 Jul 2005 20:27:19 -0400
Another problem I have coming over from Windows is the documentation
for Carbon/Cocoa/Xcode/etc. Here's my thought process:
I picked up the book "Learning Carbon", installed Xcode and was on my
way. I learned how to create a window and show it. Life is dandy.
However, now I'd like to see all the things I can do with my newly
found WindowRef. How do I close it, move it, add transparency to it,
make it spin around in circles, etc. So I fire up the documentation.
I click on Carbon....
And now I'm lost. Window, hmm, is that Fundamentals? Click. Nope,
doesn't seem like it. Doh, why doesn't the back button on my mouse
work like it does in all the other OSX apps. K, I guess I click this
little back arrow thing. Wait, that's not the page I was on before,
where did this page come from. Grr, this is getting annoying.
K, let's try API reference, that sounds good. Click. Hmm, am I
supposed to wade through all these topics trying to find the one that
pertains to me? And why are they organized by date instead of topic
or something?
K, maybe I'll search for ShowWindow instead, maybe they link to all
the other functions from there. What, why didn't the function
ShowWindow jump to the top of the list? Certainly seems like it would
have a high relevance. Oh, I see, search by API, K, found it. Hmm,
okay there's a few functions here, but surely that can't be all of them.
Let's see the cookie trail indicates that Window Manager Reference
might be a nice place to look. K, looks like this might be more
interesting. Looks like groups of functions are organized by topic, I
guess I can deal with clicking each one to see summaries, but it sure
would be handy to have a whole list.
K, ShowSheetWindow, that sounds like what I'm looking for. Now, how
do I use that? Hmm, takes two WindowRef's, okay, I know how to get
those. Hmm, does it just show it for me or do I need to provide some
sort of event handler for it. Maybe I need to setup all that stuff
ahead of time just like a regular window. Boy a small snipet of code
here would really do the job, then I could just copy & paste code
that's probably boilerplate stuff and used a lot. It'd be real handy
to know when to use a sheet to, didn't I see that info somewhere
else? Hmm, no link to any usage details or user interface guidelines.
My example here is kind of contrived, but I hope it shows what I'd
like to see in the documentation. I've spent a fair number of hours
in the last couple weeks trying out small apps in Carbon and Cocoa to
get a feel for the development process. The documentation has been
the most frustrating aspect of this process by far. I'm not a full
time OSX developer, so I have many, many languages and APIs I need to
keep in my head (which is a small finite space). I need all the help
I can get (code completion will be my next email :-)
Also hurting the documentation is the limited amount of web
resources. I pray every night that Apple will setup/sponsor a site
like www.codeproject.com for Carbon/Cocoa/etc. If that was done, then
people from all over could contribute small code snipets.
Thanks
Bill
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Xcode-users mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden