WebKit:
[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 + Change WebPreferences' userStyleSheetLocation to an NSURL.\
15 + Remove WebController's customUserAgent property.\
16 + On WebController:\
17     Add  -(BOOL)canGoBack, -(BOOL)canGoForward, -(BOOL)canCanel.\
18 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
19
20 \f1\fs24 \cf0 \
21 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
22
23 \f2\fs20 \cf0 \CocoaLigature0 + move isDocumentHTML off WebFrameView and WebDataSource\
24 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
25
26 \f1\fs24 \cf0 \CocoaLigature1 \
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 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
41 \cf2 \
42 WebHistoryItem\
43 ---\
44 \
45 Even though we need to have the fields inline for performance, we should add a few void * ivars to the end for future extensibility.\
46 \
47 WebHistoryItemPrivate,h has a boatload of private methods with no leading underscore.\
48 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
49 \cf0 Good point.\
50 \
51 \
52 \
53 On Thursday, March 20, 2003, at 11:43 AM, Ali Ozer wrote:\
54 \
55 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
56 \cf2 Some comments, mostly at the method level:\
57 \
58 \
59 WebHistory:\
60 \
61 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
62
63 \f2\fs20 \cf3 /*!\
64     @method initWithFile:\
65     @abstract The designated initializer for WebHistory.\
66     @result Returns an initialized WebHistory.\
67 */\
68 - initWithFile: (NSString *)file;\
69 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
70
71 \f1\fs24 \cf2 \
72 Would it be better to have this take a URL instead?  Like many kit classes you could limit the URLs to those on the local disk for now; but at least the API would support history lists coming from the web...  (On the other hand with WebDav and all perhaps interesting history files from the web will always be representable via file names, I don't know.)\
73 \
74 The direction in new APIs has been to use URL instead of file names where applicable...\
75 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
76 \cf0 OK.\
77 \
78 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
79 \cf2 \
80 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
81
82 \f2\fs20 \cf3 - (NSArray *)orderedLastVisitedDays;\
83 - (NSArray *)orderedEntriesLastVisitedOnDay: (NSCalendarDate *)calendarDate;\
84 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
85
86 \f1\fs24 \cf2 \
87 Why NSCalendarDate and not NSDate?\
88 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
89 \cf0 NSCalendarDate has more convenient API (i.e. the days) than NSDate?  Do you see a problem with the use of NSCalendarDate?\
90 \
91 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
92 \cf2 \
93 WebHistoryItem:\
94 \
95 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
96
97 \f2\fs20 \cf3 - (\cf4 void\cf3 )setDisplayTitle:(NSString *)displayTitle;\
98 - (NSString *)displayTitle;\
99 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
100
101 \f1\fs24 \cf2 \
102 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" ?)\
103 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
104 \cf0 Yes.  How about "displayable"?  I suppose "custom" would work too, but that doesn't feel like a good fit.\
105 \
106 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
107 \cf2 \
108 WebPluginItem:\
109 \
110 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
111
112 \f2\fs20 \cf3 - (NSString *)contentURL;\
113 - (NSString *)pluginPageURL;\
114 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
115
116 \f1\fs24 \cf2 \
117 In some other APIs where NSString containing URLs are returned, you use "...URLString" --- should maybe do that here too?\
118 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
119 \cf0 Yes, good point.\
120 \
121 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
122 \cf2 Also: Official spelling of plugin is supposed to be plugIn. At least that's what CF's plugIn mechanism had to be renamed to, and the word plugIn appears in one API in Foundation. I personally prefer plugin, like autorelease, or superview, but perhaps techpubs should bless this.\
123 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
124 \cf0 OK.  I'll check this issue.\
125 \
126 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
127 \cf2 WebKitErrors:\
128 \
129 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
130
131 \f2\fs20 \cf4 enum\cf3 \
132 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li600\ql\qnatural
133 \cf5  \{\
134     WebKitErrorCannotCreateFile,\
135     WebKitErrorCannotOpenFile,\
136     ...\
137     WebKitErrorDownloadDecodingFailedMidStream,\
138     WebKitErrorDownloadDecodingFailedToComplete,\
139 \};\
140 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
141
142 \f1\fs24 \cf2 \
143 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...\
144 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
145 \cf0 Hmm.  OK, I have no problem switching to WK in this case.\
146 \
147 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
148 \cf2 WebPreferences:\
149 \
150 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
151
152 \f2\fs20 \cf6 /*!\
153     @method standardPreferences\
154 */\cf3 \
155 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li600\ql\qnatural
156 \cf5 \
157 + (WebPreferences *)standardPreferences;\
158 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
159
160 \f1\fs24 \cf2 \
161 Should this be "shared"?  I realize NSUserDefaults uses "standard", but it's an anomaly.\
162 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
163 \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.\
164 \
165 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
166 \cf2 \
167 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
168
169 \f2\fs20 \cf6 /*!\
170     @method JavaEnabled\
171 */\cf3 \
172 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li600\ql\qnatural
173 \cf5 \
174 - (\cf4 BOOL\cf5 )JavaEnabled;\
175 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
176
177 \f1\fs24 \cf2 \
178 Are we not allowed to use "java" ?  8-)\
179 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
180 \cf0 Not sure.  I'll check with tech pubs.\
181 \
182 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
183 \cf2 Actually, I believe the guidelines prefer the use of "is" for cases like this:\
184 \
185 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
186
187 \f2\fs20 \cf2 - (void)setEditable:(BOOL)flag;\
188 - (BOOL)isEditable; \
189 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
190
191 \f1\fs24 \cf0 Yes.\
192 \
193 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
194 \cf2 so perhaps "isJavaEnabled" ? (Although there are a few more methods you'd want to change then...)\
195 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
196 \cf0 Yes, I'll make the use of 'is' consistent.\
197 \
198 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
199 \cf2 \
200 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
201
202 \f2\fs20 \cf3 - (\cf4 BOOL\cf3 )allowAnimatedImages;\
203 - (\cf4 void\cf3 )setAllowAnimatedImages:(\cf4 BOOL\cf3 )flag;\
204 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
205
206 \f1\fs24 \cf2 \
207 allowsAnimatedImages, setAllowsAnimatedImages:  (a few more examples)\
208 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
209 \cf0 Will change.\
210 \
211 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
212 \cf2 \
213 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
214
215 \f2\fs20 \cf3 - (\cf4 void\cf3 )setWillLoadImagesAutomatically: (\cf4 BOOL\cf3 )flag;\
216 - (\cf4 BOOL\cf3 )willLoadImagesAutomatically;\
217 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
218
219 \f1\fs24 \cf2 \
220 loadsImagesAutomatically, ... ?\
221 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
222 \cf0 Good suggestion.\
223 \
224 Thanks!\
225 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
226 \cf2 Ali\
227 \
228 \
229 Add loadWithData:baseURL: to WebFrame\
230 \
231 \
232 \
233 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
234 \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).\
235 \
236 Here's some suggestions for renaming the methods that don't conform to this style:\
237 \
238 \
239 WebLocationChangeDelegate\
240 \
241 - webView:willChangeLocationForDataSource:\
242 - webView:didRedirectServer:forDataSource:\
243 - webView:didCommitLocationChangeForDataSource:\
244 - webView:didReceivePageTitle:forDataSource:\
245 - webView:didReceivePageIcon:forDataSource:\
246 - webView:didFinishLocationChangeWithError:ForDataSource:\
247 \
248 Actually, perhaps -webView:didStartLocationChangeForDataSource: is more accurate. - Nancy\
249 \
250 \
251 WebResourceLoadDelegate\
252 \
253 - webView:plugInDidFailWithError:forDataSource:\
254 \
255 ** For consistency, all the "fromDataSource" text should be replaced with "forDataSource"?\
256 *** Also, replace "plugin" with "plugIn".\
257 \
258 \
259 - Nancy\
260 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
261 \cf2 \
262 \
263 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
264 \cf0 Richard,\
265 \
266 Shouldn't the WebHistory -addItems: and -removeItems: methods be named:\
267 \
268 - addItemsFromArray:\
269 - removeItemsInArray:\
270 \
271 See NSArray, NSMutableArray, NSBundle, and NSSet for similar method names.\
272 \
273 - Nancy\
274 \
275 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.\cf2 \
276 }