On Mar 1, 2005, at 12:11 PM, Laurence Harris wrote:
On 3/1/05 2:22 PM, Mike Lazear didst favor us with:
The Carbon APIs are quite sizeable and it takes a long time to learn.
I've also realized in the process that we all learn in different ways.
Larry loves the headers but is not to crazy about the sample code.
I would like it better if it were more focused. I just find it takes
longer
than I'd like to find the parts which interest me. Even then,
sometimes they
overdo it IMO. If I want to learn how to use a nib to add a custom
item to a
save dialog, for example, I don't need all the normal open dialog
handling
code (I already have that) or a sample that adds 15 different items to
a
save dialog, I just need to know the basic steps needed to add items
to the
window.
I agree. On Windows I have a set of sample code from a book about the
Windows APIs. Each sample code is very small and only shows how to use
a
specific function. Samples that are small and very concise are much
easier
to use.
AddNibToNav is a bit heavy on the items. It wouldn't be bad to have two
flavors of each sample code. AddNibToNavBasic and AddNibToNavComplete.
where the first would just show what it takes to add a window to the
Nav Open/Save
window with maybe one simple checkbox. The "complete" could be more
like
what they currently have.
For me the headers are useful when I already know the function needed
and I
want to understand the parameters otherwise I just tend to get lost.
The headers are also very valuable when you want to know what's
available if
you just read through those which are most essential to you. Searching
the
headers tends to result in a lot fewer hits than Google when searching
for
keywords. Someone asked the other day if there were a constant defined
for
the command to show the character palette, 'chrp'. I searched the
headers
for "chrp" and came up with one hit:
kHICommandShowCharacterPalette = 'chrp'
Googling for "chrp" is useless unless you're looking for the Canadian
Human
Resource Planners web site. If you Google for "chrp Apple" you get hits
about the Common Hardware Reference Platform. Searching for "chrp" on
Apple's developer site gives you 53 hits and none of them on the first
page
have anything to do with the character palette command.
I use the Project Find quite often and I would have used it to find
'chrp'. I
usually have Project Find set to "In Project and Frameworks". Thus I
would have
found 'chrp' in the header file as well.
I totally agree that headers are a great place to learn about stuff
once you know
what you are looking for, i.e. a function name, constant name or such.
But I've also been bit by searching for something like "special
characters" and not
being able to find it. Once you, or some else, points out the actual
name of the
function or constant its usually "duh, that's an obvious name".
plus several more for specific technologies which interest me.
However, that said, I still go to the headers a lot. When the headers
for
technologies such as HIToolbox contain documentation, that
documentation is
available sooner and — until the tech pubs people catch up — more
complete
and accurate than the web or PDF docs. The whole reason the engineers
started adding those comments is that tech pubs couldn't get the
information
out quickly enough. They're still the first place information will
appear in
my experience.
I'm really not trying to complain about the headers. I like that the
engineers
helped us out by adding the comments that they have. I just have a
harder
time finding what I'm looking for there unless I know the actual name of
a function or constant.
One of my biggest complaints is that there is still tons of
documentation on
Apple's site that is old, out-dated and no longer valid. It still
might make sense
to have for some developers but I wish there was a way that we could
limit
the docs that we search thru. My way around that is to add the word
Carbon
to most of my searches.
Mike
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Carbon-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
http://lists.apple.com/mailman/options/carbon-dev/email@hidden
