Notes to self.
[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\vieww16540\viewh12180\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 + put class methods from WebContentTypes back on WebController (WebView)\
24 move isDocumentHTML off WebFrameView and WebDataSource\
25 \
26 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
27
28 \f1\fs24 \cf2 \CocoaLigature1 Why are these class methods? Global per-program settings seem wrong for these. They needs to be settable per-controller.\
29 \
30 + (void)setUsesPageCache: (BOOL)flag;\
31 + (BOOL)usesPageCache;\
32 + (void)setPageCacheSize: (unsigned)size;\
33 + (unsigned)pageCacheSize;\
34 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
35 \cf0 Yes, good point.\
36 \
37 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
38 \cf2 Is it an entry or an item? Let's pick one of Item or Entry and stick to it, in both class names and method names.\
39 \
40 - (void)addEntry:(WebHistoryItem *)entry;\
41 - (void)goToEntry:(WebHistoryItem *)entry;\
42 - (WebHistoryItem *)currentEntry;\
43 - (WebHistoryItem *)forwardEntry;\
44 - (BOOL)containsEntry:(WebHistoryItem *)entry;\
45 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
46 \cf0 We will standardize on Item.\
47 \
48 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
49 \cf2 \
50 It seems non-parallel that WebHistory has change notifications but WebBackForwardList doesn't.\
51 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
52 \cf0 Yes, this is not good.  It's an artifact of implementation, not intentional design.\
53 \
54 \
55 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
56 \cf2 + (WebHistory *)createSharedHistoryWithFile: (NSString*)file;\
57 \
58 how about this (seems closer to existing Cocoa practice):\
59 \
60 +(void)setSharedHistory:(WebHistory *)history\
61 \
62 Same issue about entry vs. item for history.\
63 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
64 \cf0 Good suggestion.\
65 \
66 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
67 \cf2 WebHistoryPrivate.h (not included, but I looked) includes WebHistory methods with no leading underscore. Private methods should start with an underscore.\
68 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
69 \cf0 Yes.\
70 \
71 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
72 \cf2 \
73 WebHistoryItem\
74 ---\
75 \
76 Even though we need to have the fields inline for performance, we should add a few void * ivars to the end for future extensibility.\
77 \
78 WebHistoryItemPrivate,h has a boatload of private methods with no leading underscore.\
79 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
80 \cf0 Good point.\
81 \
82 \
83 \
84 On Thursday, March 20, 2003, at 11:43 AM, Ali Ozer wrote:\
85 \
86 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
87 \cf2 Some comments, mostly at the method level:\
88 \
89 \
90 WebHistory:\
91 \
92 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
93
94 \f2\fs20 \cf3 /*!\
95     @method initWithFile:\
96     @abstract The designated initializer for WebHistory.\
97     @result Returns an initialized WebHistory.\
98 */\
99 - initWithFile: (NSString *)file;\
100 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
101
102 \f1\fs24 \cf2 \
103 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.)\
104 \
105 The direction in new APIs has been to use URL instead of file names where applicable...\
106 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
107 \cf0 OK.\
108 \
109 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
110 \cf2 \
111 Seems like a whole lot of convenience; why not just\
112 \
113 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
114
115 \f2\fs20 \cf2 - (void)addEntries:(NSArray *)newEntries;\
116 - (void)removeEntries:(NSArray *)entries;
117 \f1\fs24 \cf2 \
118 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
119 \cf0 Yes, this suggestion is reasonable.  Add removeAll.\
120 \
121 \
122 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
123
124 \f2\fs20 \cf3 - (NSArray *)orderedLastVisitedDays;\
125 - (NSArray *)orderedEntriesLastVisitedOnDay: (NSCalendarDate *)calendarDate;\
126 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
127
128 \f1\fs24 \cf2 \
129 Why NSCalendarDate and not NSDate?\
130 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
131 \cf0 NSCalendarDate has more convenient API (i.e. the days) than NSDate?  Do you see a problem with the use of NSCalendarDate?\
132 \
133 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
134 \cf2 \
135 WebHistoryItem:\
136 \
137 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
138
139 \f2\fs20 \cf3 - (\cf4 void\cf3 )setDisplayTitle:(NSString *)displayTitle;\
140 - (NSString *)displayTitle;\
141 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
142
143 \f1\fs24 \cf2 \
144 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" ?)\
145 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
146 \cf0 Yes.  How about "displayable"?  I suppose "custom" would work too, but that doesn't feel like a good fit.\
147 \
148 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
149 \cf2 \
150 WebPluginItem:\
151 \
152 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
153
154 \f2\fs20 \cf3 - (NSString *)contentURL;\
155 - (NSString *)pluginPageURL;\
156 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
157
158 \f1\fs24 \cf2 \
159 In some other APIs where NSString containing URLs are returned, you use "...URLString" --- should maybe do that here too?\
160 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
161 \cf0 Yes, good point.\
162 \
163 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
164 \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.\
165 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
166 \cf0 OK.  I'll check this issue.\
167 \
168 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
169 \cf2 WebKitErrors:\
170 \
171 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
172
173 \f2\fs20 \cf4 enum\cf3 \
174 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li600\ql\qnatural
175 \cf5  \{\
176     WebKitErrorCannotCreateFile,\
177     WebKitErrorCannotOpenFile,\
178     ...\
179     WebKitErrorDownloadDecodingFailedMidStream,\
180     WebKitErrorDownloadDecodingFailedToComplete,\
181 \};\
182 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
183
184 \f1\fs24 \cf2 \
185 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...\
186 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
187 \cf0 Hmm.  OK, I have no problem switching to WK in this case.\
188 \
189 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
190 \cf2 WebPreferences:\
191 \
192 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
193
194 \f2\fs20 \cf6 /*!\
195     @method standardPreferences\
196 */\cf3 \
197 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li600\ql\qnatural
198 \cf5 \
199 + (WebPreferences *)standardPreferences;\
200 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
201
202 \f1\fs24 \cf2 \
203 Should this be "shared"?  I realize NSUserDefaults uses "standard", but it's an anomaly.\
204 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
205 \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.\
206 \
207 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
208 \cf2 \
209 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
210
211 \f2\fs20 \cf6 /*!\
212     @method JavaEnabled\
213 */\cf3 \
214 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li600\ql\qnatural
215 \cf5 \
216 - (\cf4 BOOL\cf5 )JavaEnabled;\
217 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
218
219 \f1\fs24 \cf2 \
220 Are we not allowed to use "java" ?  8-)\
221 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
222 \cf0 Not sure.  I'll check with tech pubs.\
223 \
224 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
225 \cf2 Actually, I believe the guidelines prefer the use of "is" for cases like this:\
226 \
227 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
228
229 \f2\fs20 \cf2 - (void)setEditable:(BOOL)flag;\
230 - (BOOL)isEditable; \
231 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
232
233 \f1\fs24 \cf0 Yes.\
234 \
235 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
236 \cf2 so perhaps "isJavaEnabled" ? (Although there are a few more methods you'd want to change then...)\
237 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
238 \cf0 Yes, I'll make the use of 'is' consistent.\
239 \
240 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
241 \cf2 \
242 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
243
244 \f2\fs20 \cf3 - (\cf4 BOOL\cf3 )allowAnimatedImages;\
245 - (\cf4 void\cf3 )setAllowAnimatedImages:(\cf4 BOOL\cf3 )flag;\
246 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
247
248 \f1\fs24 \cf2 \
249 allowsAnimatedImages, setAllowsAnimatedImages:  (a few more examples)\
250 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
251 \cf0 Will change.\
252 \
253 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
254 \cf2 \
255 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
256
257 \f2\fs20 \cf3 - (\cf4 void\cf3 )setWillLoadImagesAutomatically: (\cf4 BOOL\cf3 )flag;\
258 - (\cf4 BOOL\cf3 )willLoadImagesAutomatically;\
259 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
260
261 \f1\fs24 \cf2 \
262 loadsImagesAutomatically, ... ?\
263 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
264 \cf0 Good suggestion.\
265 \
266 Thanks!\
267 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
268 \cf2 Ali\
269 }