Reviewed by Ken.
[WebKit-https.git] / WebKit / API-Issues.rtf
1 {\rtf1\mac\ansicpg10000\cocoartf102
2 {\fonttbl\f0\fswiss\fcharset77 Helvetica-Bold;\f1\fswiss\fcharset77 Helvetica;\f2\fnil\fcharset77 Monaco;
3 }
4 {\colortbl;\red255\green255\blue255;\red0\green0\blue221;\red0\green99\blue18;\red118\green15\blue80;
5 \red84\green0\blue0;\red35\green110\blue37;}
6 \margl1440\margr1440\vieww15360\viewh16060\viewkind0
7 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
8
9 \f0\b\fs24 \cf0 API Cleanup:
10 \f1\b0 \
11 \
12 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
13
14 \f2\fs20 \cf0 + On WebController:\
15     Add  -(BOOL)canGoBack, -(BOOL)canGoForward, -(BOOL)canCanel.\
16 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
17
18 \f1\fs24 \cf0 \
19 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
20
21 \f2\fs20 \cf0 \CocoaLigature0 + move isDocumentHTML off WebFrameView and WebDataSource\
22 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
23
24 \f1\fs24 \cf0 \CocoaLigature1 \
25 Need to add other more complete action methods to WebView.\
26 \
27 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
28 \cf2 \
29 It seems non-parallel that WebHistory has change notifications but WebBackForwardList doesn't.\
30 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
31 \cf0 Yes, this is not good.  It's an artifact of implementation, not intentional design.\
32 \
33 \
34 \
35 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
36 \cf2 WebHistoryPrivate.h (not included, but I looked) includes WebHistory methods with no leading underscore. Private methods should start with an underscore.\
37 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
38 \cf0 Yes.\
39 \
40 \
41 On Thursday, March 20, 2003, at 11:43 AM, Ali Ozer wrote:\
42 \
43 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
44 \cf2 Some comments, mostly at the method level:\
45 \
46 \
47 WebHistory:\
48 \
49 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
50
51 \f2\fs20 \cf3 - (NSArray *)orderedLastVisitedDays;\
52 - (NSArray *)orderedEntriesLastVisitedOnDay: (NSCalendarDate *)calendarDate;\
53 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
54
55 \f1\fs24 \cf2 \
56 Why NSCalendarDate and not NSDate?\
57 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
58 \cf0 NSCalendarDate has more convenient API (i.e. the days) than NSDate?  Do you see a problem with the use of NSCalendarDate?\
59 \
60 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
61 \cf2 \
62 WebHistoryItem:\
63 \
64 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
65
66 \f2\fs20 \cf3 - (\cf4 void\cf3 )setDisplayTitle:(NSString *)displayTitle;\
67 - (NSString *)displayTitle;\
68 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
69
70 \f1\fs24 \cf2 \
71 It's a good idea to try to stay away from ambiguous adjectives (that are also verbs). For "display" we tend to use "localized...", but that's clearly not appropriate here. Perhaps "custom" ?  (given this is distinct than just "title" ?)\
72 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
73 \cf0 Yes.  How about "displayable"?  I suppose "custom" would work too, but that doesn't feel like a good fit.\
74 \
75 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
76 \cf2 \
77 WebKitErrors:\
78 \
79 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
80
81 \f2\fs20 \cf4 enum\cf3 \
82 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li600\ql\qnatural
83 \cf5  \{\
84     WebKitErrorCannotCreateFile,\
85     WebKitErrorCannotOpenFile,\
86     ...\
87     WebKitErrorDownloadDecodingFailedMidStream,\
88     WebKitErrorDownloadDecodingFailedToComplete,\
89 \};\
90 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
91
92 \f1\fs24 \cf2 \
93 I think this is a situation where use of "WK" would be better than "WebKit" in these cases... It also makes me think that the big reason we can get away with "Web" or "WebKit" is because these are short; using a name instead of a prefix is not a general solution...\
94 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
95 \cf0 Hmm.  OK, I have no problem switching to WK in this case.\
96 \
97 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
98 \cf2 WebPreferences:\
99 \
100 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
101
102 \f2\fs20 \cf6 /*!\
103     @method standardPreferences\
104 */\cf3 \
105 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li600\ql\qnatural
106 \cf5 \
107 + (WebPreferences *)standardPreferences;\
108 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
109
110 \f1\fs24 \cf2 \
111 Should this be "shared"?  I realize NSUserDefaults uses "standard", but it's an anomaly.\
112 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
113 \cf0 OK.  Tough to choose one over the other given the existing conflicting precedent.  I suppose 'shared' is used more often than 'standard', even though the closest analogue is the use of 'standard' in NSUserDefaults.\
114 \
115 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
116 \cf2 \
117 Add loadWithData:baseURL: to WebFrame\
118 \
119 \
120 \
121 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
122 \cf0 Looking over the 3/19 headers you sent, I noticed that some of the WebView delegate methods don't follow the Cocoa naming conventions for delegate (and notification) methods--specifically, not all of them use the keywords "will", and "did" consistently. For example, the WebLocationChangeDelegate informal protocol has a webView:willCloseLocationForDataSource: method but all of the other method names do not conform to this style. On the other hand, most of the methods in WebResourceLoadDelegate conform to this style except one. Also, some of the names use "forDataSource", and others use "fromDataSource" (which seems confusing since the sender is now a WebView).\
123 \
124 Here's some suggestions for renaming the methods that don't conform to this style:\
125 \
126 \
127 WebLocationChangeDelegate\
128 \
129 - webView:willChangeLocationForDataSource:\
130 - webView:didRedirectServer:forDataSource:\
131 - webView:didCommitLocationChangeForDataSource:\
132 - webView:didReceivePageTitle:forDataSource:\
133 - webView:didReceivePageIcon:forDataSource:\
134 - webView:didFinishLocationChangeWithError:ForDataSource:\
135 \
136 Actually, perhaps -webView:didStartLocationChangeForDataSource: is more accurate. - Nancy\
137 \
138 \
139 WebResourceLoadDelegate\
140 \
141 - webView:plugInDidFailWithError:forDataSource:\
142 \
143 ** For consistency, all the "fromDataSource" text should be replaced with "forDataSource"?\
144 *** Also, replace "plugin" with "plugIn".\
145 \
146 \
147 - Nancy\
148 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
149 \cf2 \
150 \
151 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
152 \cf0 Richard,\
153 \
154 Shouldn't the WebHistory -addItems: and -removeItems: methods be named:\
155 \
156 - addItemsFromArray:\
157 - removeItemsInArray:\
158 \
159 See NSArray, NSMutableArray, NSBundle, and NSSet for similar method names.\
160 \
161 - Nancy\
162 \
163 P.S. The WebHistory.h file you dropped a few days ago doesn't contain the file->URL changes you mentioned. Can't write the method descriptions for this class until I get the new headers.\
164 \
165
166 \f0\b From: 
167 \f1\b0 Richard Williamson <rjw@apple.com>\
168
169 \f0\b Date: 
170 \f1\b0 Mon Mar 31, 2003  4:31:00 PM US/Pacific\
171
172 \f0\b To: 
173 \f1\b0 Nancy Craighill <ncraighill@apple.com>\
174
175 \f0\b Cc: 
176 \f1\b0 Scott Anguish <sanguish@apple.com>\
177
178 \f0\b Subject: 
179 \f1\b0 Re: WK: Feedback on 3/28 Web Kit Headers\
180 \
181 \
182 On Monday, March 31, 2003, at 03:24 PM, Nancy Craighill wrote:\
183 \
184 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
185 \cf2 Richard,\
186 \
187 Incorporated the API changes as of March 28th into the current reference docs and discovered these few nits with the headers:\
188 \
189 WebPreferences.h:\
190 \
191 (1)\
192 - (void)setUserStyleSheetLocation:(NSURL *)string;\
193                                                                                 ^ Should be URL.\
194 \
195 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
196 \cf0 OK.\
197 \
198 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
199 \cf2 (2) The "Is" should be taken out of the following method names (e.g., Cocoa uses -isEnabled and -setEnabled: in NSCell, NSControl, NSFontManager, NSFontPanel, NSLayoutManager...):\
200 \
201 setIsJavaEnabled:\
202 setIsJavaScriptEnabled:\
203 \
204 NOTE: It's true that a few methods in Cocoa (four to be exact) begin with "setIs" but those methods don't contain the key word "Enabled".\
205 \
206 (3) And to be consistent, remove the "are" from this method too:\
207 \
208 setArePlugInsEnabled:\
209 \
210 Let me know if you decide NOT to make the changes above!\
211 \
212 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
213 \cf0 Gah!  I just changed these methods to include the "is" and "are"!  I thought you had made that suggestion, or maybe it was Ali.\
214 \
215 \
216 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
217 \cf2 \
218 (4) You also dropped a WebResourceResponseExtras.h header which should have been replaced by WebNSURLResponseExtras.h, right??\
219 \
220 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
221 \cf0 Yes.\
222 }