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 + 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 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
26 \cf2 \
27 It seems non-parallel that WebHistory has change notifications but WebBackForwardList doesn't.\
28 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
29 \cf0 Yes, this is not good.  It's an artifact of implementation, not intentional design.\
30 \
31 \
32 \
33 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
34 \cf2 WebHistoryPrivate.h (not included, but I looked) includes WebHistory methods with no leading underscore. Private methods should start with an underscore.\
35 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
36 \cf0 Yes.\
37 \
38 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
39 \cf2 \
40 WebHistoryItem\
41 ---\
42 \
43 Even though we need to have the fields inline for performance, we should add a few void * ivars to the end for future extensibility.\
44 \
45 WebHistoryItemPrivate,h has a boatload of private methods with no leading underscore.\
46 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
47 \cf0 Good point.\
48 \
49 \
50 \
51 On Thursday, March 20, 2003, at 11:43 AM, Ali Ozer wrote:\
52 \
53 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
54 \cf2 Some comments, mostly at the method level:\
55 \
56 \
57 WebHistory:\
58 \
59 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
60
61 \f2\fs20 \cf3 /*!\
62     @method initWithFile:\
63     @abstract The designated initializer for WebHistory.\
64     @result Returns an initialized WebHistory.\
65 */\
66 - initWithFile: (NSString *)file;\
67 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
68
69 \f1\fs24 \cf2 \
70 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.)\
71 \
72 The direction in new APIs has been to use URL instead of file names where applicable...\
73 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
74 \cf0 OK.\
75 \
76 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
77 \cf2 \
78 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
79
80 \f2\fs20 \cf3 - (NSArray *)orderedLastVisitedDays;\
81 - (NSArray *)orderedEntriesLastVisitedOnDay: (NSCalendarDate *)calendarDate;\
82 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
83
84 \f1\fs24 \cf2 \
85 Why NSCalendarDate and not NSDate?\
86 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
87 \cf0 NSCalendarDate has more convenient API (i.e. the days) than NSDate?  Do you see a problem with the use of NSCalendarDate?\
88 \
89 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
90 \cf2 \
91 WebHistoryItem:\
92 \
93 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
94
95 \f2\fs20 \cf3 - (\cf4 void\cf3 )setDisplayTitle:(NSString *)displayTitle;\
96 - (NSString *)displayTitle;\
97 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
98
99 \f1\fs24 \cf2 \
100 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" ?)\
101 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
102 \cf0 Yes.  How about "displayable"?  I suppose "custom" would work too, but that doesn't feel like a good fit.\
103 \
104 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
105 \cf2 \
106 WebKitErrors:\
107 \
108 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
109
110 \f2\fs20 \cf4 enum\cf3 \
111 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li600\ql\qnatural
112 \cf5  \{\
113     WebKitErrorCannotCreateFile,\
114     WebKitErrorCannotOpenFile,\
115     ...\
116     WebKitErrorDownloadDecodingFailedMidStream,\
117     WebKitErrorDownloadDecodingFailedToComplete,\
118 \};\
119 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
120
121 \f1\fs24 \cf2 \
122 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...\
123 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
124 \cf0 Hmm.  OK, I have no problem switching to WK in this case.\
125 \
126 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
127 \cf2 WebPreferences:\
128 \
129 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li400\ql\qnatural
130
131 \f2\fs20 \cf6 /*!\
132     @method standardPreferences\
133 */\cf3 \
134 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li600\ql\qnatural
135 \cf5 \
136 + (WebPreferences *)standardPreferences;\
137 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
138
139 \f1\fs24 \cf2 \
140 Should this be "shared"?  I realize NSUserDefaults uses "standard", but it's an anomaly.\
141 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
142 \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.\
143 \
144 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
145 \cf2 \
146 Add loadWithData:baseURL: to WebFrame\
147 \
148 \
149 \
150 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
151 \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).\
152 \
153 Here's some suggestions for renaming the methods that don't conform to this style:\
154 \
155 \
156 WebLocationChangeDelegate\
157 \
158 - webView:willChangeLocationForDataSource:\
159 - webView:didRedirectServer:forDataSource:\
160 - webView:didCommitLocationChangeForDataSource:\
161 - webView:didReceivePageTitle:forDataSource:\
162 - webView:didReceivePageIcon:forDataSource:\
163 - webView:didFinishLocationChangeWithError:ForDataSource:\
164 \
165 Actually, perhaps -webView:didStartLocationChangeForDataSource: is more accurate. - Nancy\
166 \
167 \
168 WebResourceLoadDelegate\
169 \
170 - webView:plugInDidFailWithError:forDataSource:\
171 \
172 ** For consistency, all the "fromDataSource" text should be replaced with "forDataSource"?\
173 *** Also, replace "plugin" with "plugIn".\
174 \
175 \
176 - Nancy\
177 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\li200\ql\qnatural
178 \cf2 \
179 \
180 \pard\tx560\tx1120\tx1680\tx2240\tx2800\tx3360\tx3920\tx4480\tx5040\tx5600\tx6160\tx6720\ql\qnatural
181 \cf0 Richard,\
182 \
183 Shouldn't the WebHistory -addItems: and -removeItems: methods be named:\
184 \
185 - addItemsFromArray:\
186 - removeItemsInArray:\
187 \
188 See NSArray, NSMutableArray, NSBundle, and NSSet for similar method names.\
189 \
190 - Nancy\
191 \
192 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.\
193 \
194 \
195 From WebHistory.h:\
196 \
197 // Notifications sent when history is modified.\
198 // The first two come with a userInfo dictionary with a single key "Entries", which contains\
199 // an array of items that were added or removed.\
200 \
201 The API has been updated to always call the things items instead of entries, but this key is:\
202 \
203     1) still "Entries"\
204     2) still a constant in a comment, rather than an NSString constant\
205 \
206 I think we should fix this.\
207 \
208     -- Darin\
209 }