Re: [NOOB] Finding Information (was: real noob question)
Re: [NOOB] Finding Information (was: real noob question)
- Subject: Re: [NOOB] Finding Information (was: real noob question)
- From: mmalc Crawford <email@hidden>
- Date: Mon, 19 Jan 2009 08:17:06 -0800
On Jan 19, 2009, at 6:10 AM, julius wrote:
I too followed up on the example link which took me to the top of
the NSDecimalNumber Class reference document. Scrolling down the
first thing I came accross under Tasks was "Creating a Decimal
Number" and just beneath that a link to
+ decimalNumberWithDecimal:
which looked exactly like what the OP was asking for, viz:
<>
Creates and returns an NSDecimalNumber object equivalent to a given
NSDecimal structure.
+ (NSDecimalNumber *)decimalNumberWithDecimal:(NSDecimal)decimal>
</>
Ah, and look perhaps I don't need to use an alloc....
Now with all respect to the writers of this documentation, my first
question is "what is a decimal structure?".
Typically here I would either click the link to NSDecimal in the
method declaration, or go to the Companion Guide listed at the top of
the API reference.
Or ... (see below)
I followed up on NSDecimal and obtained:
[...]
Scareeeeeee!!!! and nothing like what I thought it might be.
So either back to NSDecimalNumber, or to the Companion Guide.
I have had reason to think about this quite frequently and have come
to the conclusion that there is nothing simple or straightforward
about writing easy to use technical manuals.
Indeed.
One of the main problems it seems to me occurs when I'm trying to
get quickly to an answer and rather than read and digest every word
of the manual
I have had reason to think about this quite frequently and have come
to the conclusion that, when documentation is written, it should be
padded with extraneous words and phrases that readers can safely ignore.
O.K. lets leave that and go back to see if we can find something
that looks a bit more like the OP's number : 23.30.
The next heading beneath "Creating a Decimal Number" is
"Initializing a Decimal Number" and head of the list is
<>
– initWithDecimal:
</>
That looks promising.. but
<>
initWithDecimal:
Returns an NSDecimalNumber object initialized to represent a given
decimal.
- (id)initWithDecimal:(NSDecimal)decimal>
</>
No good: there's that NSDecimal again, but note that this time it is
not described as a structure but as a "decimal" !!!!
Back to the top of the list:
<>
Initializing a Decimal Number
* – initWithDecimal:
* – initWithMantissa:exponent:isNegative:
* – initWithString:
* – initWithString:locale:
</>
But there is nothing here that looks anything like it would allow me
to intialise with a numeric value like 23.30.
It's not clear why, throughout, you have ignored:
(a) initWithMantissa:exponent:isNegative:
(b) "Inherits from NSNumber : NSValue : NSObject"
In this case, (b) might have actually lead you astray(*), but it
should have been in your search path.
(*) <http://www.cocoabuilder.com/archive/message/cocoa/2009/1/10/227253>
(You did search the archives as well, didn't you?)
I'll stop here.
Why?
At this stage, although you should actually have found an answer, you
should have at least looked at the Companion Guide and if that didn't
address the issue you should have sent in feedback using either the
form at the bottom of each documentation page or using Radar.
My point is that learning a system via the manual is not the easiest
thing in the world and just pointing people at specific pages in the
manual though helpful is not always necessarily the best way of
doing things.
Looking at just the API reference pages is typically as useful a way
to learn about Cocoa as using a dictionary to learn a foreign
language. If you want to learn about how methods etc. are used in
context, then turn to the Companion Guides.
One of those imponderable mysteries I guess. But someone must have
thought it worthwhile.... so why not say so in the documentation?
All the references to Companion Guide above notwithstanding, as it
happens, this isn't well addressed in the Guide. Please either send
feedback or file a Radar (<http://bugreport.apple.com/>) to have this
addressed.
mmalc
_______________________________________________
Cocoa-dev mailing list (email@hidden)
Please do not post admin requests or moderator comments to the list.
Contact the moderators at cocoa-dev-admins(at)lists.apple.com
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden