Re: bad documentation
Re: bad documentation
- Subject: Re: bad documentation
- From: "Erik M. Buck" <email@hidden>
- Date: Mon, 12 Nov 2001 22:17:04 -0600
>
Let us start with a few general statements:
>
- Classes tab in PB is really a GREAT improvement, but still has a number
>
of problems (already detailed in this list and project-builder list). I
>
would like to congratulate the PB team about it.
>
OK
>
- Sherlock is still (quite) broken in MacOS X (used to be great in OS 9)
>
and Help Viewer is just a (bad) joke. Period.
>
Agreed
>
- Searching. Used to be very bad in Apple's site; probably improved by the
>
Google engine. Still, you must be connected to Internet. The only decent
>
way to search in your hard disk is the PB 'find' panel, but only for
>
definitions. So improve Sherlock or Help Viewer.
>
Or restore DigitalLibrarian.app. MTLibrarian and other applications are
also useful. A google search on the entire internet is usually fruitful.
There are hundreds of examples and tutorials and full applications with
source code out there.
>
- 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.
>
Foundation classes are in categories in AppKit (like NSBunde for instance)
>
and THERE IS NO LINK IN BETWEEN. Not only is it difficult to handle when
There are links from Application Kit to Foundation Kit. It would be WRONG
to have links from Foundation Kit to Application Kit.
>
you already know it (you have to navigate a lot), but it's very difficult
>
to figure out otherwise, particularly if you learned OOP in another
>
language. Remember that in C++ and Java it is not possible to add method
>
to a class. There is a huge difference between just reading a book
>
explaining protocols, and really understanding their power.
This is true of many language features. Predicates in Prolog are cool too.
>
>-> WE NEED an html page summarizing all Cocoa classes/protocol/functions
>
(an index).
I would love to have a comprehensive cross index of all APIs available on
OS-X.
>
>
-- 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.
>
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.
>
>
-- At the very top of every page of the doc, there is a two links
>
"documentation":"cocoa". YOU CANNOT follow them, because they correspond
>
to a link 'help:something' that no browser understand. (Okay there is Help
>
Viewer; who is laughing?) Even PB cannot follow one these link (the most
>
useful: coca).
We all agree that AppleHelp and HelpViewer are worthless. Apple should
remove these bogus links ASAP and replace them with useful links.
>
>
-- 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.
>
>
> Overview of Programming Topic: Basic Drawing
>
>
>
> Description forthcoming.
>
>
>
>
>
> Child Topics
>
>
>
> None
>
>
>
>
>
> Discussion
>
>
>
> This topic is under construction.
>
>
>
No comment! (That's now more than one year that Mac OS X is out, remember
>
?)
>
>
-- So to find useful information you MUST read the classes description.
OK. I don't anticipate this ever changing.
>
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
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
>
NSConnection (the only example, but it's incomplete) are obvious but the
>
most useful is NSApplication, for detachDrawingThread:)!
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
>
>
-- Finally I'm not the only one to say that is (still) a large number of
>
errors/incorrect statements in the doc. Cocoa experts should take a look
>
(and fill a bug report) about the doc on copyWithZone for instance
>
(exercise: where is this method documented?). In my opinion, the line that
>
starts with
>
Product *copy = [[Product alloc]
>
is just plain wrong; it should be
>
Product *copy = [[[self class] alloc]
>
...and this makes a HUGE difference when subclassing (which is the very
>
difficult point here).
>
Good catch!
>
Incidentally there is a very interesting sentence in this page:
>
> "When a class inherits NSCopying behavior, you must consider the
>
> possibility that the superclass's implementation uses NSCopyObject(). "
>
That's funny because the documentation does NEVER explain if a class uses
>
NSCopyObject() to copy objects.
>
>
Okay enough for today it 0:11 here in France!
>
Good point! Maybe the documentation should not expose implementation
details. The implementatiion of copying might change from version to
version. Perhapse that is why programmers should consider the possibility
and not asume it uses NSCopyObject or not. I wounder why I have never been
harmed by this.
>
Yours,
>
>
Thomas Lachand-Robert