Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Thierry Faucounau <email@hidden>
- Date: Fri, 8 Jul 2005 08:12:17 +0200
On Jul 6, 2005, at 8:06 PM, Tim Conkling wrote:
On Jul 5, 2005, at 2:51 PM, Chris Hanson wrote:
On Jul 5, 2005, at 9:46 AM, Brandon Sneed wrote:
Despite VS.NET's UI being awful, writing code that works is made
extremely easy by the good quality documentation and automation
of common tasks.
Can you elaborate on your latter point (automation of common
tasks) a bit?
-- Chris
I'd like to chime in here.
As would I :)
I have recently had to work on a Carbon app and have been struggling
with the very poor documentation for the Mac's new red headed
stepchild (I cannot wait to get back to fullscreen OpenGL apps after
the insane struggle this has been).
The particular case I would like to outline is this, for the last
hour I have been trying to locate possible error codes for HIView
functions. Pretty much all of the documentation for Carbon functions
ends with this very unhelpful phrase:
function result: An operating system status code.
Now that is all good and well, but it would seem that MacErrors.h
(where I used to look for these things) is no longer around (just a
one line stub that #includes <CoreServices/CoreServices.h>).
In contrast, most (if not all) of the MS docs I have dealt with (D3D
for the most part) clearly enumerate the possible error codes that a
particular method can return. This just seems like a good practice to
me.
Now I do have an older version of MacErrors.h from my CW install but
I cannot seem to figure out if the error codes it contains are still
around and valid (afraid I have not done a lot of Carbon coding in
the last 5-6 years).
Searching ADC, the on disk docs or grepping through the sea of header
files has so far born little fruit (HIView.h itself contains one(!)
error define for errNeedsCompositedWindow). I would appreciate any
help anyone could give.
This recent experience has driven home for me a lot of the points
made in this thread. Basically, many aspects of the current docs are
just not up to snuff right now.
Ah, but for the days when reading Inside Mac Volume 6 would cut off
the blood flow to your legs :) And Kon & Bal, bring back Kon & Bal!
Thierry Faucounau
Senior 3D Engineer -- Zonic
http://www.zonic.co.uk/games/
_______________________________________________
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