- async programming style, Promise return and method naming
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
in the main thread since the editor / model changed.
o would be good to have a naming theme that makes our model clear. We could for example use:
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.
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
is not observable. Example updateSelection. Otherwise people might think updateSelection(xxx).then(() => selction is at position xxx which might not be the case).
- label, names, descriptions: would be great to indicate if they show up in the user interface and therefore must be human readable.
- 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
- 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
inside and even need to communicate that back to the outside.
*/
...
...
@@ -77,49 +61,44 @@ declare namespace vscode {
}
/**
* Represents a line of text such as a line of source code
* <<< Is a textLine live. E.g. when updating the document will a text line update as well. If not
* I would suggest to remove TextLine and add the methods to text document. Otherwise the object might
* be misleading.
* >>>
* Represents a line of text such as a line of source code.
*
* TextLine objects are __immutable__. That means that when a [document](#TextDocument) changes
* previsouly retrieved lines will not represent the latest state.
*/
exportinterfaceTextLine{
/**
* The zero-offset line number <<<better: 'zero-based' see https://en.wikipedia.org/wiki/Zero-based_numbering >>>
* The zero-base line number.
*
* @readonly
*/
lineNumber:number;
/**
* The text of this line without the
* newline character <<< what's about CR/LF on Windows? better: 'line separator characters' >>>
* The text of this line without the line separator characters.
*
* @readonly
*/
text:string;
/**
* The range this line covers without the
* newline character <<< what's about CR/LF on Windows? better: 'line separator characters' >>>
* The range this line covers without the line separator characters.
*
* @readonly
*/
range:Range;
/**
* The range this line covers with the
* newline character <<< dito >>>
* The range this line covers with the line separator characters.
*
* @readonly
*/
rangeIncludingLineBreak:Range;
/**
* The offset of the first character which
* isn't a whitespace character as defined
* by a `\s`-RegExp
* The offset of the first character which is not a whitespace character as defined
* by `/\s/`.
*
* @readonly
*/
...
...
@@ -141,16 +120,17 @@ declare namespace vscode {
exportinterfaceTextDocument{
/**
* Get the associated URI for this document. Most documents have the file://-scheme, indicating that they represent files on disk.
* However, some documents may have other schemes indicating that they are not available on disk.
* The associated URI for this document. Most documents have the __file__-scheme, indicating that they
* represent files on disk. However, some documents may have other schemes indicating that they are not
* available on disk.
*
* @readonly
*/
uri:Uri;
/**
* Returns the file system path of the file associated with this document. Shorthand
* notation for `#uri.fsPath` <<< what if uri is not a file? >>>
* The file system path of the associated resource. Shorthand
* notation for `#uri.fsPath`. Independent of the uri scheme.
*
* @readonly
*/
...
...
@@ -164,7 +144,7 @@ declare namespace vscode {
isUntitled:boolean;
/**
* The language identifier associated with this document.
* The identifier of the language associated with this document.
*
* @readonly
*/
...
...
@@ -232,25 +212,36 @@ declare namespace vscode {
positionAt(offset:number):Position;
/**
* Get the text in this document. If a range is provided the text contained
* by the range is returned. <<< if the range is larger than the TextDocument only the intersection is ... >>>
* Get the text of this document. A substring can be retrieved by providing
* a range. The range will be [adjusted](#TextDocument.validateRange).
*
* @param range Include only the text included by the range.
*/
getText(range?:Range):string;
/**
* Get the word under a certain position. May return null if position is at whitespace, on empty line, etc.
* <<< what is a 'word'? >>>
* Get a word-range at the given position. By default words are defined by
* common separators, like space, -, _, etc. In addition, per languge custom
* [word definitions](#LanguageConfiguration.wordPattern) can be defined.
*
* @param position A position.
* @return A range spanning a word, or `undefined`.
*/
getWordRangeAtPosition(position:Position):Range;
/**
* Ensure a range sticks to the text.
* <<< 'sticks'? better: ensure a range is completely contained in the TextDocument. >>>
* Ensure a range is completely contained in this document.
*
* @param range A range.
* @return The given range or a new, adjusted range.
*/
validateRange(range:Range):Range;
/**
* Ensure a position sticks to the text. // <<< dito >>>
* Ensure a position is completely contained in this document.
*
* @param position A position.
* @return The given position or a new, adjusted position.
*/
validatePosition(position:Position):Position;
}
...
...
@@ -362,16 +353,21 @@ declare namespace vscode {
* Create a new range from two position. If `start` is not
* before or equal to `end` the values will be swapped.
*
* @param start
* @param end
* @param start A position.
* @param end A position.
*/
constructor(start:Position,end:Position);
/**
* Create a new range from two (line,character)-pairs. The parameters
* Create a new range from four number. The parameters
* might be swapped so that start is before or equal to end.
*
* @param startLine A positive number or zero.
* @param startCharacter A positive number or zero.
* @param endLine A positive number or zero.
* @param endCharacter A positive number or zero.
*/
constructor(startLine:number,startColumn:number,endLine:number,endColumn:number);// <<< use 'character' instead of 'column' >>>