Re: Documentation frustrations
Re: Documentation frustrations
- Subject: Re: Documentation frustrations
- From: Andy Lee <email@hidden>
- Date: Sat, 9 Jul 2005 23:01:08 -0400
On Jul 9, 2005, at 3:06 AM, mmalcolm crawford wrote:
One possible remedy comes to mind:
At the top of each class reference is a box that lists, "Inherits
from", "Conforms to" etc. This seems like a reasonable place to
also list categories. Would this be an acceptable solution? If
so, please... :-)
There are two cases where I care (documentationally speaking) that a
class implements categories: when the category is an informal
protocol, and when the category is an addition made by a framework
other than the class's main framework (like the AppKit Addition
methods on NSString). There is a third case where categories are
documented, namely delegate methods, but those are generally not
categories on the class in question, and they are handled specially.
I haven't kept track of which of these cases are being discussed
here, but I think it was the informal protocol case.
I do think informal protocols should be listed next to "Inherits
From", "Conforms to", etc. I wouldn't call it a list of categories,
but a list of Informal Protocols that the class implements. You
already have a page for each informal protocol, so a link to that
page tells the programmer what they want to know. The grammar is a
bit tricky -- the obvious name for this section is "Informal
Protocols" but that doesn't end with a preposition like "Inherits
From", etc. -- but you folks can solve that somehow, I'm sure.
If there is something special about how the class implements one of
the informal protocol methods, you could have a section in the class
document that lists "Methods That Conform To Informal Protocol Foo".
Come to think of it -- instead of (or in addition to) grouping the
informal protocols with the "Conforms to" section, you should list
the methods in a group under the Method Types section.
A related question is whether the "Informal Protocols" list should be
repeated in the doc for each subclass. Offhand I'd say yes, since
the "Conforms to" information appears to be repeated.
As for the other case where I care about categories -- the "AppKit
Additions" to NSString case -- I just discovered that NSString.html,
which is the Foundation doc for NSString, has a link to the NSString
Additions page, but it is embedded in a paragraph about the class
rather than listed in a structured section of the document. The
CoreImage doc file CIColor.html doesn't have a link at all to the
AppKit Additions to CIColor, which is inconsistent and also means a
reader might not find what they want.
FWIW, the doc browser I wrote, AppKiDo, handles AppKit Additions to
NSString by listing both the main docs (in Foundation) and the
"addition" docs side by side:
<http://homepage.mac.com/aglee/downloads/1.jpg>
"Addition" methods are listed alongside the non-category methods, and
are marked with the name of the framework that makes the "addition,"
in this case AppKit:
<http://homepage.mac.com/aglee/downloads/2.jpg>
--Andy
_______________________________________________
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