• Open Menu Close Menu
  • Apple
  • Shopping Bag
  • Apple
  • Mac
  • iPad
  • iPhone
  • Watch
  • TV
  • Music
  • Support
  • Search apple.com
  • Shopping Bag

Lists

Open Menu Close Menu
  • Terms and Conditions
  • Lists hosted on this site
  • Email the Postmaster
  • Tips for posting to public mailing lists
Still about bad documentation
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Still about bad documentation


  • Subject: Still about bad documentation
  • From: email@hidden
  • Date: Tue, 13 Nov 2001 12:37:19 +0100

Erick,

I woudl like to seize the occasion to explain differently my point about the bad documentation, unsing one of your own answer to R. Brockerhoff (in digest #834). It seems to me a very good example.

Message: 10
From: "Erik M. Buck" <email@hidden>
To: <email@hidden>, "Rainer Brockerhoff"
<email@hidden>
Subject: Re: Controlling selection in NSTextFields
Date: Sat, 10 Nov 2001 17:56:55 -0600

First of all I notice that the original author is Rainer Brockerhoff. He is to some point a beginner in Cocoa, but actually commited a great application named XRay. (And I personnaly don't know any bug in XRay...). Should only 10% of "beginners" do the same, MacOSX would crunch Windows 'digitas in naso pedesque super tabulam'.

Well, the embedded NSText object is damnably difficult to get ahold
of,
[[myTextField window] fieldEditor:YES forObject:myTextField ]; // this is
not damnably difficult


The Field Editor <long citation about it>

Erick you just prove that it is indeed difficult. How do YOU know where to find the method 'fieldEditor'? That's you know that there IS a field editor, located IN THE WINDOW. Both of them are NOT obvious at all (actually that's a huge difference between TextField and other controls). It is so obvious to you that you didn't even mention the origin of the citation about the field editor. So for others, I explain: this comes from NSWindow's class documentation (immersed in a lot of other windows attributes).

There is also NSControl's
currentEditor
- (NSText *)currentEditor

And now we are turning on to NSControl... Okay, it is the parent class of NSTextField, but should the doc indicate that NSTextField override this one, this would be MUCH easier to understand, don't you think?

I like
- (BOOL)textShouldBeginEditing:(NSText *)aTextObject

and/or

- (void)textDidBeginEditing:(NSNotification *)aNotification

These one are in NSTextField's documentation, but in NSControl you find
control:textShouldBeginEditing:
and a number of others, plus the definition of the notifications. I use Cocoa for one year and still doesn't understand this repartition of methods/notifications.
Again, should the NSTextField's documentation recall these methods (there are LIKELY to be overrident by NSTextField, but I'm not sure), this would be harmless.

The point is that to find the info on this case you have to look to three classes doc, one of them not obviously related to the problem.

Thomas Lachand-Robert
********************** email@hidden
<< Et le chemin est long du projet ` la chose. >> Molihre, Tartuffe.


  • Follow-Ups:
    • Re: Still about bad documentation
      • From: Rainer Brockerhoff <email@hidden>
    • Re: Still about bad documentation
      • From: Stéphane Sudre <email@hidden>
  • Prev by Date: Re: bad documentation
  • Next by Date: Re: bad documentation
  • Previous by thread: NSPopUpList ClassNotFoundException
  • Next by thread: Re: Still about bad documentation
  • Index(es):
    • Date
    • Thread