Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Uli Kusterer <email@hidden>
- Date: Sat, 9 Jul 2005 18:54:11 +0200
On Jul 9, 2005, at 14:16 , Dietmar Planitzer wrote:
On Jul 9, 2005, at 9:44 AM, Scott Anguish wrote:
Well, I personally still don't understand why the methods defined
in the NSWindowScripting category are not documented in the
NSWindow reference ?
Same here. I think there should be cross-references between an
object's main docs and the docs to all its methods, *and back*. I
already filed various bugs against this. E.g. I feel rather proud
that I filed the bug that brought you links between NSString and
NSMutableString.
I don't see how breaking up the documentation of a single class
into multiple individual documents is of any help. In fact I think,
and as this sub-thread has shown, it makes it harder to find what
people are looking for.
Well, that depends. There are lots of object methods that are very
specific to very arcane uses, and more important methods may get
buried in a huge list of methods. So, grouping them by category on
the same page may actually make it easier to find certain methods
(though setIsVisible: is obviously the counter-example), and
splitting off the most arcane methods into separate files could be an
attempt to achieve the same (not to mention keep Apple's bandwidth
requirements and our load times low).
I'd also like the ability to collapse/uncollapse categories in this
list (a la Google groups). So, by default it'd only show the main and
most important methods, and then you can uncollapse additional
categories. Of course, a "uncollapse all" button and a "collapse less
important methods" link would be handy here.
There are exactly two important keywords in the problem statement
above: showing/hiding and window. Therefor, it's most likely that
the person who is looking for documentation on his problem is going
to look into the NSWindow reference and looking for methods having
to do with showing and hiding windows. The last thing we can expect
is that everyone has a list of each and every category stored in
his mind which would allow him to instantly know where exactly to
look for the documentation of a particular method.
This is the simple reason why _all_ methods of a class, no matter
if they are for whatever reason declared in a category or not,
should be listed in the reference of that class without exception.
I mainly agree. Though, if setIsVisible: really is wrong to use,
it'd help to add a comment to orderOut: and orderFront: and
orderFrontAndMakeKey: to use them instead of setIsVisible:, and the
same in setIsVisible:. This is, IMHO, one of the main problems of the
docs: Some links only exist in one direction. They should always be
*required* to be in both directions.
I think providing the inherited informal protocols for things
would be good, Right now we document the formal protocols in the
'table' at the top of the class.. the name of the protocol and, if
it is from a superclass, the superclass in brackets. The same
thing could be done with informal protocols.
No, no, please don't do this.
This kind of information would not be of any help. It would not
help me to find the documentation of a method faster, it would not
help me to make my program better or faster in general. It would
however blow up the inheritance section in terms of size of many
classes to the point where it would become quite hard to find the
actually relevant inheritance information: namely the list of super-
classes. Just consider what it would mean for the inheritance
section of the NSArray class. This is a case where the principle
that "more is not necessarily better" should be taken note of.
Well, I'd definitely want at *least* links to other categories in
the main header. Even better, link to all categories and the main
header from all other categories, so I can flip through all
categories and search sequentially through them. But IMHO all methods
in a single file with collapsing would be better. Or at least have
that feature in Xcode's documentation browser, if the webmaster can't
load-balance the additional accesses from the beginners who're just
looking for the superclass or init method signature.
I personally think that while informal protocols or categories are
a good organizational tool on the implementation level, they are
not much if not of no relevance on the documentation level. I think
that the organization of the documentation of a particular class in
terms of its categories does not help the documentation, does not
make it easier to understand or find information. In fact I think
they unnecessarily make it harder to find information on that level.
It depends on the category in question. Most categories on NSString
aren't really that interesting, but e.g. NSStringPathUtilities
definitely deserve being in a separate group, even though I wouldn't
demand they be put in a separate file (OTOH I could understand an
argument being made for it). I guess ideally there would be an editor
who'd manually decide what categories go on the main page and which
ones get their own files. But lacking that, linking to all other
categories or grouping by category and having everything in a honkin'
huge file would definitely be more desirable, I'd say.
Cheers,
-- M. Uli Kusterer
http://www.zathras.de
_______________________________________________
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