Re: Frameworks refernce online...
Re: Frameworks refernce online...
- Subject: Re: Frameworks refernce online...
- From: Andy Lee <email@hidden>
- Date: Thu, 22 Aug 2002 16:39:57 -0400
At 11:11 AM -0700 8/22/02, James Duncan Davidson wrote:
On Tuesday, Aug 20, 2002, at 15:48 US/Pacific, Jonathan Jackel wrote:
Andy Lee's AppKiDo is also a terrific way to use the documentation. Much
better than Cocoa Browser, in my opinion.
http://homepage.mac.com/aglee/downloads
Before all else, I'm really glad there's multiple people working on
this from different approaches. It's all way more usable than using
a web browser. I hope that this can be considered to be constructive
criticism that will help the developers of both pieces of software.
It is taken as such (by me anyway), but I do appreciate your courtesy
in making that clear.
At first glance, it looks better because there's more UI,
I don't equate "more UI" with "better," but I think I know what you mean.
but at this time, I don't like it as much. The reasons why:
1) The top class browser puts everything into a class
inheritance hierarchy. So to use the browser, I have to know where a
class is in the hierarchy. Cocoa Browser displays everything
together, so it's easy to find. Yes, AppKiDo has the drawer which
has the alpha lists of classes--but all that means is that I've not
got a browser which I don't want to use and more screen real estate
taken up by all the UI at the top of the drawer. Bottom line--the
non class hierarchy list is better and only needs to show up once.
I don't agree that one approach is inherently better. As
programmers, our browsing needs change throughout a project -- heck,
throughout the day. With AppKiDo you have a choice -- browser or
flat list. With a click or two, you can hide either, neither, or
both. (You may not have noticed, but you *can* hide and unhide the
browser.)
AppKiDo's browser lets you go to a class's superclass with one click.
In Cocoa Browser, if you're looking at a class's instance methods and
want to see its superclass's instance methods, you have to go to the
current class's top-level doc, click on the "Inherits from:" link,
then drill back down to "Instance Methods." In AppKiDo, this whole
operation is reduced to one click. You can efficiently search for
methods up and down the hierarchy.
Cocoa Browser provides *no* way, efficient or otherwise, to see all
the subclasses of a class. Sometimes this can be useful for a newbie
(or even an oldbie who's exploring).
2) The Find button on the drawer looks inviting, but only
works with a complete class name.
Not true. It does a prefix search. So "nstabl <return>" lists all
the classes (*and* protocols) associated with tables, because they
happen to have that prefix. Likewise, "nstext <return>" lists
classes and protocols associated with text views.
If I want to see all classes with "Control" in it because I'm not
sure which control to use, it doesn't work.
This particular example is not a good one. No subclass of NSControl
has "Control" in its name. (How do I know? I used AppKiDo's
hierarchy browser.) I think a more likely case is, you want to see
all classes with "Cell" in the name. You might be wondering what
kind of cell you should use for a particular purpose. This is
something I've wondered on different occasions -- and it's why you
can see a list of all the NSCell classes with one click in AppKiDo's
drawer. I figured that would be a common need, and the browser
doesn't quite help enough, because the NSCell subclasses go three
levels down.
More generally, I *might* improve AppKiDo's Find function to accept
wildcard characters so you can do something like "NS*Cell <return>".
But no promises.
3) No Function or Types reference. They've said it's coming,
but. Until it's there, I can't use it much at all as that's where I
spent a lot of time looking for documentation.
Agreed, Functions ought to be in there, and it's my bad for putting
it off so long (over a month already).
If I were to try to defend the current state of the app, I might say
AppKiDo is designed to do one thing well -- browse classes and
protocols, period. That's where most of *my* doc needs lie. For the
rest, there's MTLibrarian -- and of course, Cocoa Browser.
4) No Java reference. Objective-C only.
Right, no argument there -- Cocoa Browser is the place to go for Java docs.
My gut feeling, without having thought through the details, is that a
Cocoa doc browser specialized for the Java classes should be
*slightly* different than an Objective-C one. But anyway, I'm not
going there in the near future.
6) No way reference on Protocols, Classes only right now.
Lots of functionality is buried in those Protocols.
Excuse me, there are protocol docs. They start at the top level of
the hierarchy browser. Protocols are also listed in the Find
results, if there are any. You can tell them by the angle brackets
around the name. And if you click on a link to a protocol in any of
the documentation, you are taken to the doc for that protocol.
(By the way, while making sure that there wasn't protocol docs, I
clicked on NSString in the AppKit list and got the Foundation
NSString docs...)
Aha! Another difference between Cocoa Browser and AppKiDo. The fact
is, NSString is *both* an AppKit class *and* a Foundation class. I
don't know how much time I've wasted looking for a method that I
*knew* was in a "Foundation" class before I realized I should be
looking in the AppKit extension (i.e., category) for that class.
Okay, call me a slow learner. But in AppKiDo, you see all NSString
methods in the same list.
To be sure, there's a few things I wish were different in Cocoa Browser:
[...]
3) Having four parts to the browser is a little crowded.
AppKiDo might have discovered something by using the list of classes
down the side
You caught on to part of my reasoning. I don't like scrolling long
lists in short columns, so I made my list as tall as possible.
Anyways, just my thoughts... :)
They're appreciated.
I think AppKiDo complements other tools, which is why I usually
recommend MTLibrarian as well. I also recommend Cocoa Browser if you
need Java documentation or docs for things AppKiDo doesn't cover.
As always, use whatever works for you. I get paid the same either way.
--Andy
_______________________________________________
cocoa-dev mailing list | email@hidden
Help/Unsubscribe/Archives:
http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored.