You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- async programming style, Promise return and method naming
34
-
o we should make a statement how the async programming style works. What happens if I call a method and the actual operation can not be executed
35
-
in the main thread since the editor / model changed.
36
-
o would be good to have a naming theme that makes our model clear. We could for example use:
37
-
setXXX/applyXXX => Thenable. The operation is either done or rejected. An example is applying edits which get rejected if the model version doesn't exist anymore.
38
-
updateXXX => void. The operation is done but the result might never be observable. It could even be that the operation got dropped. Or we want to ensure the operation
39
-
is not observable. Example updateSelection. Otherwise people might think updateSelection(xxx).then(() => selction is at position xxx which might not be the case).
26
+
40
27
- label, names, descriptions: would be great to indicate if they show up in the user interface and therefore must be human readable.
41
-
- usage of option bags. Most functions flatten all parameters other only take an option bag. We should be consistent here. If option bags they must be optional
42
-
- param: T | Thenable<T>: (e.g. showQuickPick). IMO we shouldn't pass Thenable as a param. It should be resolved outside> Otherwise we need to handle the error case
43
-
inside and even need to communicate that back to the outside.
44
28
*/
45
29
46
30
@@ -77,49 +61,44 @@ declare namespace vscode {
77
61
}
78
62
79
63
/**
80
-
* Represents a line of text such as a line of source code
81
-
* <<< Is a textLine live. E.g. when updating the document will a text line update as well. If not
82
-
* I would suggest to remove TextLine and add the methods to text document. Otherwise the object might
83
-
* be misleading.
84
-
* >>>
64
+
* Represents a line of text such as a line of source code.
65
+
*
66
+
* TextLine objects are __immutable__. That means that when a [document](#TextDocument) changes
67
+
* previsouly retrieved lines will not represent the latest state.
85
68
*/
86
69
exportinterfaceTextLine{
87
70
88
71
/**
89
-
* The zero-offset line number <<<better: 'zero-based' see https://en.wikipedia.org/wiki/Zero-based_numbering >>>
72
+
* The zero-base line number.
90
73
*
91
74
* @readonly
92
75
*/
93
76
lineNumber: number;
94
77
95
78
/**
96
-
* The text of this line without the
97
-
* newline character <<< what's about CR/LF on Windows? better: 'line separator characters' >>>
79
+
* The text of this line without the line separator characters.
98
80
*
99
81
* @readonly
100
82
*/
101
83
text: string;
102
84
103
85
/**
104
-
* The range this line covers without the
105
-
* newline character <<< what's about CR/LF on Windows? better: 'line separator characters' >>>
86
+
* The range this line covers without the line separator characters.
106
87
*
107
88
* @readonly
108
89
*/
109
90
range: Range;
110
91
111
92
/**
112
-
* The range this line covers with the
113
-
* newline character <<< dito >>>
93
+
* The range this line covers with the line separator characters.
114
94
*
115
95
* @readonly
116
96
*/
117
97
rangeIncludingLineBreak: Range;
118
98
119
99
/**
120
-
* The offset of the first character which
121
-
* isn't a whitespace character as defined
122
-
* by a `\s`-RegExp
100
+
* The offset of the first character which is not a whitespace character as defined
101
+
* by `/\s/`.
123
102
*
124
103
* @readonly
125
104
*/
@@ -141,16 +120,17 @@ declare namespace vscode {
141
120
exportinterfaceTextDocument{
142
121
143
122
/**
144
-
* Get the associated URI for this document. Most documents have the file://-scheme, indicating that they represent files on disk.
145
-
* However, some documents may have other schemes indicating that they are not available on disk.
123
+
* The associated URI for this document. Most documents have the __file__-scheme, indicating that they
124
+
* represent files on disk. However, some documents may have other schemes indicating that they are not
125
+
* available on disk.
146
126
*
147
127
* @readonly
148
128
*/
149
129
uri: Uri;
150
130
151
131
/**
152
-
* Returns the file system path of the file associated with this document. Shorthand
153
-
* notation for `#uri.fsPath` <<< what if uri is not a file? >>>
132
+
* The file system path of the associated resource. Shorthand
133
+
* notation for `#uri.fsPath`. Independent of the uri scheme.
154
134
*
155
135
* @readonly
156
136
*/
@@ -164,7 +144,7 @@ declare namespace vscode {
164
144
isUntitled: boolean;
165
145
166
146
/**
167
-
* The language identifier associated with this document.
147
+
* The identifier of the language associated with this document.
168
148
*
169
149
* @readonly
170
150
*/
@@ -232,25 +212,36 @@ declare namespace vscode {
232
212
positionAt(offset: number): Position;
233
213
234
214
/**
235
-
* Get the text in this document. If a range is provided the text contained
236
-
* by the range is returned. <<< if the range is larger than the TextDocument only the intersection is ... >>>
215
+
* Get the text of this document. A substring can be retrieved by providing
216
+
* a range. The range will be [adjusted](#TextDocument.validateRange).
217
+
*
218
+
* @param range Include only the text included by the range.
237
219
*/
238
220
getText(range?: Range): string;
239
221
240
222
/**
241
-
* Get the word under a certain position. May return null if position is at whitespace, on empty line, etc.
242
-
* <<< what is a 'word'? >>>
223
+
* Get a word-range at the given position. By default words are defined by
224
+
* common separators, like space, -, _, etc. In addition, per languge custom
225
+
* [word definitions](#LanguageConfiguration.wordPattern) can be defined.
226
+
*
227
+
* @param position A position.
228
+
* @return A range spanning a word, or `undefined`.
0 commit comments