maxmustermann/vscode
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

jsdoc vscode.d.ts

Browse source
This commit is contained in:
Johannes Rieken 2015-11-13 17:31:15 +01:00
parent cc9e65cea2
commit d62a44820f
1 changed files with 78 additions and 74 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

152
src/vs/vscode.d.ts vendored
View file

@ -5,7 +5,6 @@
/*
- comments are marked like this '<<< comment >>>'
- I've fixed typos directly without comments
some global comments:
- I'm missing some structure/grouping in this file:
@ -24,23 +23,8 @@
"To get an instance of a {{FileSystemWatcher}} use {{workspace.createFileSystemWatcher}}."
- lots of class or method comments are still missing. If we cannot create all of them in time, we should focus on comments for non-obvious cases.
I have added a "non-obvious" comment.
- unclear when we have functions in a namespace and when we have resolve function and a sub namespace / interface. Examples are:
o workspace.openTextDocument() => return ITextDocument which opens a separate namespace
o vscode.language.register* functions. Could have been workspace.getLanguage(selector) => ILangauge
In general I think that having separate namespaces will help with scalibility. Results in smaller proposals in code complete.
window.activeTextEditor.###, window.statusBar.###, window.quickPick.###
- 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.
*/
export interface TextLine {
/**
* 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 {
export interface TextDocument {
/**
* 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' >>>
constructor(startLine: number, startCharacter: number, endLine: number, endCharacter: number);
/**
* `true` iff `start` and `end` are equal.
@ -437,8 +433,13 @@ declare namespace vscode {
/**
* Create a selection from four points.
*
* @param anchorLine A positive number or zero.
* @param anchorCharacter A positive number or zero.
* @param activeLine A positive number or zero.
* @param activeCharacter A positive number or zero.
*/
constructor(anchorLine: number, anchorColumn: number, activeLine: number, activeColumn: number); // <<< 'column' -> 'character' >>>
constructor(anchorLine: number, anchorCharacter: number, activeLine: number, activeCharacter: number);
/**
* A selection is reversed if the [anchor](#Selection.anchor)
* is equal to [start](#Selection.start) and if [active](#Selection.active)
@ -475,7 +476,7 @@ declare namespace vscode {
/**
* A text editor decoration type is a handle to additional styles in
* the editor.
* the editor.
*
* To get an instance of a `TextEditorDecorationType` use
* [createTextEditorDecorationType](#window.createTextEditorDecorationType).
@ -619,15 +620,12 @@ declare namespace vscode {
document: TextDocument;
/**
* The primary selection on this text editor. In case the text editor has multiple selections this is the first selection as
* in `TextEditor.selections[0]`. <<< and in the single selection case this is not true? This should always be true! >>>
* @see [updateSelection](#updateSelection)
* The primary selection on this text editor. Shorthand for `TextEditor.selections[0]`.
*/
selection: Selection;
/**
* The selections in this text editor.
* @see [updateSelection](#updateSelection)
* The selections in this text editor. The primary selection is always at index 0.
*/
selections: Selection[];
@ -638,17 +636,24 @@ declare namespace vscode {
/**
* Perform an edit on the document associated with this text editor.
* The passed in {{editBuilder}} is available only for the duration of the callback.
* <<< waht does 'available' mean? better: 'valid' >>>
*
* The given callback-function is invoked with an [edit-builder](#TextEditorEdit) which must
* be used to make edits. Note that the the edit-builder is only valid while the
* callback executes.
*
* @param callback A function which can make edits using an [edit-builder](#TextEditorEdit).
* @return A promise that resolve when the edits could be applied.
*/
edit(callback: (editBuilder: TextEditorEdit) => void): Thenable<boolean>;
/**
* Adds a set of decorations to the text editor.
* You must first create a `TextEditorDecorationType`. <<< to create another object is probably true for 95% of all APIs; nuke this sentence! >>>
* If a set of decorations already exists with the given type, they will be overwritten.
* Adds a set of decorations to the text editor. If a set of decorations already exists with
* the given [decoration type](#TextEditorDecorationType), they will be replaced.
*
* @param decorationType A decoration type.
* @param rangesOrOptions Either [ranges](#Range) or more detailed [options](#DecorationOptions).
*/
setDecorations(decorationType: TextEditorDecorationType, ranges: Range[] | DecorationOptions[]): void;
setDecorations(decorationType: TextEditorDecorationType, rangesOrOptions: Range[] | DecorationOptions[]): void;
/**
* Scroll as necessary in order to reveal the given range.
@ -676,17 +681,6 @@ declare namespace vscode {
hide(): void;
}
/**
* Denotes a column in the VS Code window. Columns used to show editors
* side by side.
* <<< another reason not to use the term 'column' for 'character' within a line >>>
* <<< this definition seems to be misplaced: it is not TextEditor related >>>
*/
export enum ViewColumn {
One = 1,
Two = 2,
Three = 3
}
/**
* A complex edit that will be applied on a TextEditor.
@ -910,12 +904,12 @@ declare namespace vscode {
export interface QuickPickItem {
/**
* The main label of this item <<< is there another 'non-main' label? >>>
* A label. Will be rendered prominent.
*/
label: string;
/**
* A description <<< for what is this used? >>>
* A description. Will be rendered less prominent.
*/
description: string;
}
@ -936,7 +930,7 @@ declare namespace vscode {
}
/**
* Represents an actional item that is shown with an information, warning, or <<< what is an 'actional' item? >>>
* Represents an action that is shown with an information, warning, or
* error message
*
* @see #window.showInformationMessage
@ -1524,6 +1518,16 @@ declare namespace vscode {
dispose(): void;
}
/**
* Denotes a column in the VS Code window. Columns used to show editors
* side by side.
*/
export enum ViewColumn {
One = 1,
Two = 2,
Three = 3
}
/**
* An output channel is a container for readonly textual information.
*