Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: mmalcolm crawford <email@hidden>
- Date: Sat, 9 Jul 2005 15:14:32 -0700
On Jul 9, 2005, at 12:02 AM, Raffael Cavallaro wrote:
On Jul 9, 2005, at Sat, Jul 9, 2:21 14 AM, mmalcolm crawford wrote:
What would be helpful would be if you gave concrete examples.
NSWindow API Reference has well over a hundred methods - or is it
200? - and precisely 9 lines of sample code - if you count comments:
I would have to file enhancement requests for most of the API
references - sample code in the API references is as scarce as
water in a desert.
(a) This is simply untrue.
I believe my example of NSWindow shows that my statement is very true.
I probably see there as being less water in a desert than you do.
Moreover, I take into account the location of the water -- there are
places it's not useful, and if you had too much of it you'd drown.
A single class does not represent the whole reference. Moreover,
it's not clear what purpose examples would serve for many of the
methods -- most are simple accessor methods, or have a direct effect.
makeKeyAndOrderFront:
- (void)makeKeyAndOrderFront:(id)sender
This action method moves the receiver to the front of the screen
list, within its level, and makes it the key window.
For example:
[aWindow makeKeyAndOrderFront:self];
// window is made key and is ordered front...
See Also: – makeMainWindow, – becomeKeyWindow, – isKeyWindow
recalculateKeyViewLoop
- (void)recalculateKeyViewLoop
Marks the key view loop as dirty and in need of recalculation. The
key view loop is actually recalculated the next time someone requests
the next or previous key view of the window. The recalculated loop is
based on the geometric order of the views in the window.
If you do not want to maintain the key view loop of your window
manually, you can use this method to do it for you. When it is first
loaded, NSWindow calls this method automatically if your window does
not have a key view loop already established. If you add or remove
views later, you can call this method manually from your code to
update the window’s key view loop. You can also call
setAutorecalculatesKeyViewLoop: to have the window recalculate the
loop automatically.
For example:
[aWindow recalculateKeyViewLoop];
// window key view loop is marked as dirty...
Availability
Available in Mac OS X v10.4 and later.
See Also: – selectKeyViewFollowingView:, –
selectKeyViewPrecedingView:, – setAutorecalculatesKeyViewLoop:
Contrast with other classes, such as NSMutableArray and
NSManagedObjectContext...
What would be more useful would be concrete examples of individual
methods that could benefit from in-line examples. Such as, NSArray's
sortedArrayUsingFunction:context:hint:. It should be possible to
create a largely self-contained example that illustrates the use of
this method -- in contrast to, say, drawRect:...
No, it's because it's a good example of a case where simply giving
a code sample in isolation is unlikely to be useful. I would be
very interested to know how you would approach the issue.
The easiest thing to do would be to provide pointers to existing
sample code that show how one overrides NSView's drawRect: method
such as:
It's not clear how to reconcile this suggestion with your original
assertion that the reference itself should contain sample code, and
that there should be "one authoritative source"?
Pointers to already existing sample code would require the least
work on the part of you and your colleagues, and be minimally
intrusive to the existing API reference. I've no doubt that you or
some colleague could write a script that would parse the existing
API references and insert a single link for each method to a page
linking to all the locations in which that method is used in
existing sample code. Minimally intrusive - a single link saying
"example code" for each method, constant, etc., - and minimal work
- linking to a page with every location in sample code that has
already been written. You'd have to add anchors to the html
versions of the sample code, but that could be automated as well.
(a) There isn't any reasonable way to do this with the current
production tools.
(b) You can already do this yourself, and the results show why this
approach will not work:
<http://developer.apple.com/cgi-bin/search.pl?q=drawRect:&num=10&site=
(samplecode)>. This gives 170 matches. Not all are valid, showing
that a more sophisticated algorithm would be required. A significant
number are, however, valid, and it does not seem reasonable to list,
say 30 or 40 links to sample code in a single method definition -- it
would certainly not be "minimally intrusive"...
mmalc
_______________________________________________
Do not post admin requests to the list. They will be ignored.
Cocoa-dev mailing list (email@hidden)
Help/Unsubscribe/Update your Subscription:
This email sent to email@hidden