Re: bad documentation
Re: bad documentation
- Subject: Re: bad documentation
- From: email@hidden
- Date: Tue, 13 Nov 2001 11:04:08 +0100
Le mardi 13 novembre 2001, ` 05:17 , Erik M. Buck a icrit :
- About the HTML documentation:
I usually read it using OmniWeb. Not because it's fast (it's not), but
because it has a great system to organize bookmarks. The main
inconvenient
in the HTML docs is that they are NOT ORGANIZED. Examples:
-- Classes are separated in Foundation/AppKit frameworks. That just
doesn'
t make sense while programming an app. Some very useful methods for
That is called encapsulation. The Foundation Kit does not have any
dependencies on the Application Kit. The Application Kit extends the
Foundation Kit. The fact that the Application Kit can include categories
that add methods to Foundation classes is a very powerful feature of
Objective-C. If you are looking at the AppKit you will see the methods.
If
you are looking at the Foundation Kit you should NOT see them. Categories
let framework designers avoid violations of encapsulation and still put
code
where it belongs.
That why I said it doesn't make sense while programming an APP. You will
need both frameworks anyway, so you don't bother which is independent from
the other (the situation is different while using only the Foundation
though). Anyway I just don't understand why it would be bad to have in
NSBundle's documentation:
"Note that Application Kit extends NSBundle by adding the following
methods:
- list of methods (+ hypertext links!)"
More generally there is A LOT of missing links in the documentation. Here
is an example among others. The doc of NSControl begins with:
"Conforms to:
NSCoding (NSResponder)
NSObject (NSObject)"
There is no link here (FOUR needed!). It continue with the sentence:
"Subclasses of NSControl defined in the Application Kit are NSBrowser,
NSButton (and its subclass NSPopUpButton), NSColorWell, NSImageView,
NSMatrix (and its subclass NSForm), NSScroller, NSSlider, NSTableView, and
NSTextField. Instances of concrete NSControl subclasses are often referred
to as, simply, controls."
That sentence doesn't contain any single link! Etc.
There are links from Application Kit to Foundation Kit. It would be WRONG
to have links from Foundation Kit to Application Kit.
NO IT WOULDN'T, if there are correctly referenced as links to another
framework.
-- Classes are indicated with their inheritance path, but the inherited
methods are not even mentioned. This makes difficult to understand their
behavior. It would be sufficient to recall the name of inherited (and non
I already advocated that ever class's documentation include every message
the class can understand. I find it unnecessary, but I understand that
needing only one document at a time is an advantage over having to shuffle
many documents at once to answer a question.
It is necessary. Also the documentation should explain which superclass
method is overriden, with the changes, because it is just a new behavior
of the subclass. This apply also to related classes, in particular the
delegate. For instance NSOutlineView inherits from NSTableView, which has
a delegate. Should the delegate of an NSOutlineView implements the
delegate methods of NSTableView? It turns out that no, because
NSOutlineView delegate methods "override" each delegate method of
NSTableView. But IT IS NOT STATED AS IS in the doc, and it is difficult to
understand since here the "overriden" methods have DIFFERENT names. (They
shouldn't in my opinion; anyway...)
overriden) methods, with a hypertext link. As a good example of class
documantation, take a look on the java classes doc at
http://java.sun.com/
j2ee/sdk_1.3/techdocs/api/index.html
(You don't need to like java ;-)
There is still no overview in this documentation. You have to know what
to
look for before you can find it just like with the Cocoa documentation.
That's why I said "a good example of class documentation" (sorry for the
typo). At least you know for each class all acceptable methods. Yesterday
the compiler surprised me by telling that "NSMutableArray doesn't respond
to enumerator". I had to search the doc, go back to NSArray, and finally
found that the correct name is "objectEnumerator" (Sounds very unnatural
to me; I never remember this one!). And that's just a basic example.
-- If you manage to go to the Cocoa main page, as I'm pretty sure that
most experts never do, you will find something interesting: at the lower
part of the page, there is AT LAST some organization, with the general
title "Programming Topics". Now read on, say "basic drawing" (something
simple to start on). You will get (in large characters):
There are many alternative sources for this type of information. Search
with google.
I know that, you keep telling that every day here in the list ;-)
The point is that beginners obviously look first at Apple docs. Maybe
Apple could add links to Google searches, if they can't complete the doc..
.
Anyway a search will not answer the organization question: how are drawing
classes (in this example) organized. Who is drawing where? etc. Internet
searches usually give a large number of partial answers, and to get a
complete picture you need to make the puzzle yourself.
That means that you must understand the connections between the classes.
Exercise: you want to have information on doing a multithreaded
application, where should you look? Answer: NSThread (NOT NSTask),
Search thread or NSThread in google.
http://www.google.com/search?num=100&hl=en&q=nsthread+apple+developer&btnG=
G
oogle+Search
I did, using your own link. There is 71 answers, but I still can't find
NSApplication detachDrawingThread:, which the most useful thread method
(particularly for beginners), even though I know it should be there. Can
you ?
http://www.google.com/search?as_q=thread+apple+developer&num=100&btnG=Google
+Search&as_epq=&as_oq=&as_eq=&lr=&as_ft=i&as_filetype=&as_qdr=all&as_occt=
an
y&as_dt=i&as_sitesearch=&safe=off
I particularly like the following found with the above search:
http://developer.apple.com/techpubs/macosx/Cocoa/Reference/ApplicationKit/
Ob
jC_classic/Classes/NSApplication.html
Now I get 25900 answers. Can't find NSApplication inside. Anyway no
beginner would expect an interesting method related to threading for this
link!
Thomas Lachand-Robert
********************** email@hidden
<< Et le chemin est long du projet ` la chose. >> Molihre, Tartuffe.