Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Raffael Cavallaro <email@hidden>
- Date: Sun, 10 Jul 2005 13:48:42 -0400
- Resent-date: Sun, 10 Jul 2005 13:49:08 -0400
- Resent-from: Raffael Cavallaro <email@hidden>
- Resent-message-id: <email@hidden>
- Resent-to: Cocoa Developers <email@hidden>
On Jul 9, 2005, at Sat, Jul 9, 6:14 32 PM, mmalcolm crawford wrote:
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"...
First of all, you don't include .c and .h and readme files when
searching for sample code uses of Objective-C methods. So the "more
sophisticated algorithm" consists of:
1. Searching only .m files of existing sample code of all occurrences
of the method in question *and* the class in question. Then you clean
up the results by removing duplicates or if you want an even shorter
link list, any hits that occur within the same .m file. If you want
to be conservative, search for the two - the selector and class -
within a certain distance of each other.
Would you miss some relevant examples?
Probably.
Would you get some false positives?
Probably.
Would you yield a bunch of useful links to already existing sample code?
Definitely.
Could you spend more than a couple of man-days cleaning up the results?
Yes.
Do you really need to clean up these results for them to be extremely
useful?
No.
Considering the current fragmented and often inaccurate state of the
documentation, having a page of links to sample code some of which
might not be useful is nothing to be dismissed so lightly. If you
need to CYA, you just put a disclaimer at the top of the auto-
generated page stating that it was generated by an automated process
and some of the links might not be relevant.
Second, I suggested a single link labeled "sample code" for each
method in the API docs. That link, when clicked on, would go to a
page with a list of every occurrence of that method and class in a .m
file in the existing sample code. That would be, I assert:
1. minimally intrusive - it would consist of a single link "sample
code" for each method in the existing API reference docs. If people
don't want to see that auto-generated page, they just don't click on
the link. That's all. The additional two words "sample code" for each
method in the API reference are easily ignored by those who don't
want to see the auto-generated sample code list.
2. automatic - it would link to a page listing every occurrence of
the method and class in question within a certain distance of each
other in a sample code .m file. Perfect? no. Very useful? Definitely.
3. most importantly, it leverages already existing assets using
minimal manpower resources to very good end.
Finally to the notion that you can "already do this yourself," no,
really you cannot. You cannot restrict searches to .m files. If I
search for:
drawRect: NSView .m
It still pulls up header files and readme files which could easily be
excluded by a simple parser script. And we can't do proximity
searches either.
Finally, we don't have these parser/search results at our fingertips
within the API Reference docs where they would be most useful.
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