Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Raffael Cavallaro <email@hidden>
- Date: Sat, 9 Jul 2005 03:02:20 -0400
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:
--------------------
if ([myWindow makeFirstResponder:myWindow]) {
/* All fields are now valid; it’s safe to use
fieldEditor:forObject:
to claim the field editor. */
}
else {
/* Force first responder to resign. */
[myWindow endEditingFor:nil];
}
-----------
[myWindow setResizeIncrements:NSMakeSize(1.0,1.0)];
------------------------
If you find places where you believe the API reference would
benefit from code samples, please file enhancement requests.
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.
It does not help the case if you make inaccurate statements (or,
regarding other issues, indulge in baseless speculation).
(b) If you don't file bug reports, then it's certainly not going to
be fixed.
And again it would be interesting if you could provide an outline
for the NSView drawRect: method.
I don't follow you here - is this intended to be sarcastic
because NSView is an abstract class?
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:
<http://developer.apple.com/samplecode/PDFView/listing7.html>
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.
regards,
Ralph
Raffael Cavallaro, Ph.D.
email@hidden
_______________________________________________
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