• Open Menu Close Menu
  • Apple
  • Shopping Bag
  • Apple
  • Mac
  • iPad
  • iPhone
  • Watch
  • TV
  • Music
  • Support
  • Search apple.com
  • Shopping Bag

Lists

Open Menu Close Menu
  • Terms and Conditions
  • Lists hosted on this site
  • Email the Postmaster
  • Tips for posting to public mailing lists
Re: bad documentation
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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.


References: 
 >Re: bad documentation (From: "Erik M. Buck" <email@hidden>)

  • Prev by Date: Re: New Cocoa Programmer
  • Next by Date: Re: Localized dates and times
  • Previous by thread: Re: bad documentation
  • Next by thread: Re: bad documentation
  • Index(es):
    • Date
    • Thread