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

More jsdoc for extension API

Browse source
This commit is contained in:
Johannes Rieken 2015-11-16 22:35:15 +01:00
parent 9b27a0b6d9
commit 6293737e69
1 changed files with 136 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -793,7 +793,6 @@ declare namespace vscode {
hide(): void; hide(): void;
} }
/** /**
* A complex edit that will be applied in one transaction on a TextEditor. * A complex edit that will be applied in one transaction on a TextEditor.
* This holds a description of the edits and if the edits are valid (i.e. no overlapping regions, document was not changed in the meantime, etc.) * This holds a description of the edits and if the edits are valid (i.e. no overlapping regions, document was not changed in the meantime, etc.)
@ -828,21 +827,27 @@ declare namespace vscode {
delete(location: Range | Selection): void; delete(location: Range | Selection): void;
} }
/** /**
* A universal resource identifier representing either a file on disk on * A universal resource identifier representing either a file on disk on
* or another resource, e.g untitled. * or another resource, like untitled resources.
*/ */
export class Uri { export class Uri {
/** /**
* Create URI for a file system path * Create an URI from a file system path. The [scheme](#Uri.scheme)
* will be `file`.
*
* @param path A file system or UNC path.
* @return A new Uri instance.
*/ */
static file(path: string): Uri; static file(path: string): Uri;
/** /**
* Create an URI from a string. Will throw if the given value is not
* valid.
* *
* @param The string value of an Uri.
* @return A new Uri instance.
*/ */
static parse(value: string): Uri; static parse(value: string): Uri;
@ -894,30 +899,27 @@ declare namespace vscode {
* A cancellation token is passed to asynchronous or long running * A cancellation token is passed to asynchronous or long running
* operation to request cancellation, like cancelling a request * operation to request cancellation, like cancelling a request
* for completion items because the user continued to type. * for completion items because the user continued to type.
*
* A cancellation token can only cancel once. That means it
* signaled cancellation it will do so forever <<< don't understand this >>>
*/ */
export interface CancellationToken { export interface CancellationToken {
/** /**
* `true` when the token has been cancelled. * Is `true` when the token has been cancelled, `false` otherwise.
*/ */
isCancellationRequested: boolean; isCancellationRequested: boolean;
/** /**
* An [event](#Event) which fires upon cancellation * An [event](#Event) which fires upon cancellation.
*/ */
onCancellationRequested: Event<any>; onCancellationRequested: Event<any>;
} }
/** /**
* A cancellation source creates [cancellation tokens](#CancellationToken). * A cancellation source creates and controls a [cancellation token](#CancellationToken).
*/ */
export class CancellationTokenSource { export class CancellationTokenSource {
/** /**
* The current token * The cancellation token of this source.
*/ */
token: CancellationToken; token: CancellationToken;
@ -927,14 +929,11 @@ declare namespace vscode {
cancel(): void; cancel(): void;
/** /**
* Signal cancellation and free resources <<< so this is like 'cancel()'? then the name is a bit harmless (or misleading) ... >>> * Dispose object and free resources. Will call [cancel](#CancellationTokenSource.cancel).
*/ */
dispose(): void; dispose(): void;
} }
// <<< Should we have an IDispose interface people can implement by themselves and then push into a subscriptions
// instead of always creating an extra object and a function >>>
/** /**
* Represents a type which can release resources, such * Represents a type which can release resources, such
* as event listening or a timer. * as event listening or a timer.
@ -973,9 +972,9 @@ declare namespace vscode {
/** /**
* *
* @param listener The listener function will be called when the event happens. * @param listener The listener function will be called when the event happens.
* @param thisArgs The 'this' which will be used when calling the event listener. * @param thisArgs The `this`-argument which will be used when calling the event listener.
* @param disposables An array to which a {{IDisposable}} will be added. The * @param disposables An array to which a [disposeable](#Disposable) will be added.
* @return * @return A disposable which unsubscribes the event listener
*/ */
(listener: (e: T) => any, thisArgs?: any, disposables?: Disposable[]): Disposable; (listener: (e: T) => any, thisArgs?: any, disposables?: Disposable[]): Disposable;
} }
@ -1504,9 +1503,7 @@ declare namespace vscode {
} }
/** /**
* A workspace edit represents textual changes for many documents. When applying a workspace edit, * A workspace edit represents textual changes for many documents.
* the editor implements an 'all-or-nothing'-strategy, that means failure to load one document or
* make changes to one document will make this edit being ignored.
*/ */
export class WorkspaceEdit { export class WorkspaceEdit {
@ -1755,15 +1752,24 @@ declare namespace vscode {
}; };
} }
/**
* Represents the workspace configuration. The workspace configuration
* is always a merged view of the configuration of the current [workspace](#workspace.rootPath)
* and the installation-wide configuration.
*/
export interface WorkspaceConfiguration { export interface WorkspaceConfiguration {
/** /**
* @param section configuration name, supports _dotted_ names * Return a value from this configuration.
* @return the value `section` denotes or the default *
* @param section Configuration name, supports _dotted_ names.
* @return The value `section` denotes or the default.
*/ */
get<T>(section: string, defaultValue?: T): T; get<T>(section: string, defaultValue?: T): T;
/** /**
* Check if this configuration has a certain value.
*
* @param section configuration name, supports _dotted_ names * @param section configuration name, supports _dotted_ names
* @return `true` iff the section doesn't resolve to `undefined` * @return `true` iff the section doesn't resolve to `undefined`
*/ */
@ -1951,7 +1957,6 @@ declare namespace vscode {
*/ */
append(value: string): void; append(value: string): void;
/** /**
* Append the given value and a line feed character * Append the given value and a line feed character
* to the channel. * to the channel.
@ -1968,7 +1973,7 @@ declare namespace vscode {
/** /**
* Reveal this channel in the UI. * Reveal this channel in the UI.
* *
* @column The column in which to show the channel, default in [one](#ViewColumn.One). * @param column The column in which to show the channel, default in [one](#ViewColumn.One).
*/ */
show(column?: ViewColumn): void; show(column?: ViewColumn): void;
@ -2172,29 +2177,43 @@ declare namespace vscode {
* Registers a command that can be invoked via a keyboard shortcut, * Registers a command that can be invoked via a keyboard shortcut,
* an menu item, an action, or directly. * an menu item, an action, or directly.
* *
* @param command - The unique identifier of this command * Registering a command with an existing command identifier twice
* @param callback - The command callback * will cause an error.
* @param thisArgs - (optional) The this context used when invoking {{callback}} *
* @return Disposable which unregisters this command on disposal * @param command A unique identifier for the command.
* @param callback A command handler function.
* @param thisArgs The `this` context used when invoking handler function.
* @return Disposable which unregisters this command on disposal.
*/ */
export function registerCommand(command: string, callback: (...args: any[]) => any, thisArg?: any): Disposable; export function registerCommand(command: string, callback: (...args: any[]) => any, thisArg?: any): Disposable;
/** /**
* Register a text editor command that will make edits. * Registers a text editor command that can be invoked via a keyboard shortcut,
* It can be invoked via a keyboard shortcut, a menu item, an action, or directly. * an menu item, an action, or directly.
* *
* @param command - The unique identifier of this command * Text editor commands are different from ordinary [commands](#commands.registerCommand) as
* @param callback - The command callback. The {{textEditor}} and {{edit}} passed in are available only for the duration of the callback. * they only execute when there was an active editor when the command was called. Also, the
* @param thisArgs - (optional) The `this` context used when invoking {{callback}} * command handler of an editor command has access to the active editor and to an
* @return Disposable which unregisters this command on disposal * [edit](#TextEditorEdit)-builder.
*
* @param command A unique identifier for the command.
* @param callback A command handler function with access to an [editor](#TextEditor) and an [edit](#TextEditorEdit).
* @param thisArgs The `this` context used when invoking handler function.
* @return Disposable which unregisters this command on disposal.
*/ */
export function registerTextEditorCommand(command: string, callback: (textEditor: TextEditor, edit: TextEditorEdit) => void, thisArg?: any): Disposable; export function registerTextEditorCommand(command: string, callback: (textEditor: TextEditor, edit: TextEditorEdit) => void, thisArg?: any): Disposable;
/** /**
* Executes a command * Executes the command denoted by the given command identifier.
* *
* @param command - Identifier of the command to execute * When executing an editor command not all types are allowed to
* @param ...rest - Parameter passed to the command function * be passed as arguments. Allows are the primitive types `string`, `boolean`,
* `number`, `undefined`, and `null`, as well as classes defined in this API.
* There are no restriction when executing commands that have been contributed
* by extensions.
*
* @param command Identifier of the command to execute.
* @param ...rest Parameter passed to the command function.
* @return * @return
*/ */
export function executeCommand<T>(command: string, ...rest: any[]): Thenable<T>; export function executeCommand<T>(command: string, ...rest: any[]): Thenable<T>;
@ -2253,7 +2272,10 @@ declare namespace vscode {
export function showTextDocument(document: TextDocument, column?: ViewColumn): Thenable<TextEditor>; export function showTextDocument(document: TextDocument, column?: ViewColumn): Thenable<TextEditor>;
/** /**
* Create a `TextEditorDecorationType` that can be used to add decorations to text editors. * Create a TextEditorDecorationType that can be used to add decorations to text editors.
*
* @param options Rendering options for the decoration type.
* @return A new decoration type instance.
*/ */
export function createTextEditorDecorationType(options: DecorationRenderOptions): TextEditorDecorationType; export function createTextEditorDecorationType(options: DecorationRenderOptions): TextEditorDecorationType;
@ -2337,7 +2359,7 @@ declare namespace vscode {
export function setStatusBarMessage(text: string): Disposable; export function setStatusBarMessage(text: string): Disposable;
/** /**
* @see [[#window.setStatusBarMessage]] * @see [window.setStatusBarMessage](#window.setStatusBarMessage)
* *
* @param hideAfterTimeout Timeout in milliseconds after which the message will be disposed. * @param hideAfterTimeout Timeout in milliseconds after which the message will be disposed.
* @return A disposable which hides the status bar message. * @return A disposable which hides the status bar message.
@ -2345,7 +2367,7 @@ declare namespace vscode {
export function setStatusBarMessage(text: string, hideAfterTimeout: number): Disposable; export function setStatusBarMessage(text: string, hideAfterTimeout: number): Disposable;
/** /**
* @see [[#window.setStatusBarMessage]] * @see [window.setStatusBarMessage](#window.setStatusBarMessage)
* *
* @param hideWhenDone Thenable on which completion (resolve or reject) the message will be disposed. * @param hideWhenDone Thenable on which completion (resolve or reject) the message will be disposed.
* @return A disposable which hides the status bar message. * @return A disposable which hides the status bar message.
@ -2356,7 +2378,7 @@ declare namespace vscode {
* Creates a status bar [item](#StatusBarItem). * Creates a status bar [item](#StatusBarItem).
* *
* @param position The alignment of the item. * @param position The alignment of the item.
* @param priority The priority of the item. Higher value means the item should be shown more to the left. * @param priority The priority of the item. Higher values mean the item should be shown more to the left.
* @return A new status bar item. * @return A new status bar item.
*/ */
export function createStatusBarItem(alignment?: StatusBarAlignment, priority?: number): StatusBarItem; export function createStatusBarItem(alignment?: StatusBarAlignment, priority?: number): StatusBarItem;
@ -2403,28 +2425,45 @@ declare namespace vscode {
export namespace workspace { export namespace workspace {
/** /**
* Creates a file system watcher. A glob pattern that filters the * Creates a file system watcher.
* file events must be provided. Optionally, flags to ignore certain
* kind of events can be provided.
* *
* @param globPattern - A glob pattern that is applied to the names of created, changed, and deleted files. * A glob pattern that filters the file events must be provided. Optionally, flags to ignore certain
* @param ignoreCreateEvents - Ignore when files have been created. * kind of events can be provided. To stop listening to events the watcher must be disposed.
* @param ignoreChangeEvents - Ignore when files have been changed. *
* @param ignoreDeleteEvents - Ignore when files have been deleted. * @param globPattern A glob pattern that is applied to the names of created, changed, and deleted files.
* @param ignoreCreateEvents Ignore when files have been created.
* @param ignoreChangeEvents Ignore when files have been changed.
* @param ignoreDeleteEvents Ignore when files have been deleted.
* @return A new file system watcher instance.
*/ */
export function createFileSystemWatcher(globPattern: string, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher; export function createFileSystemWatcher(globPattern: string, ignoreCreateEvents?: boolean, ignoreChangeEvents?: boolean, ignoreDeleteEvents?: boolean): FileSystemWatcher;
/** /**
* The folder that is open in VS Code if applicable * The folder that is open in VS Code. `undefined` when no folder
* has been opened.
*/ */
export let rootPath: string; export let rootPath: string;
/** /**
* @return a path relative to the [root](#rootPath) of the workspace. * Returns a path that is relative to the workspace root.
*
* When there is no [workspace root](#workspace.rootPath) or when the path
* is not a child of that folder, the input is returned.
*
* @param pathOrUri A path or uri. When a uri is given its [fsPath](#Uri.fsPath) is used.
* @return A path relative to the root or the input.
*/ */
export function asRelativePath(pathOrUri: string | Uri): string; export function asRelativePath(pathOrUri: string | Uri): string;
// TODO@api - justify this being here /**
* Find files in the workspace.
*
* @sample findFiles('**\*.js', '**\node_modules\**', 10)
* @param include A glob pattern that defines the files to search for.
* @param exclude A glob pattern that defined files and folders to exclude.
* @param maxResults An upper-bound for the result.
* @return A thenable that resolves to an array of resource identifiers.
*/
export function findFiles(include: string, exclude: string, maxResults?: number): Thenable<Uri[]>; export function findFiles(include: string, exclude: string, maxResults?: number): Thenable<Uri[]>;
/** /**
@ -2433,12 +2472,22 @@ declare namespace vscode {
export function saveAll(includeUntitled?: boolean): Thenable<boolean>; export function saveAll(includeUntitled?: boolean): Thenable<boolean>;
/** /**
* Apply the provided [workspace edit](#WorkspaceEdit). * Make changes to one or many resources as defined by the given
* [workspace edit](#WorkspaceEdit).
*
* When applying a workspace edit, the editor implements a 'all-or-nothing'-strategy,
* that means failure to load one document or make changes to one document will make
* the edit be rejected.
*
* @param edit A workspace edit.
* @return A thenable that resolves when the edit could be applied.
*/ */
export function applyEdit(edit: WorkspaceEdit): Thenable<boolean>; export function applyEdit(edit: WorkspaceEdit): Thenable<boolean>;
/** /**
* All text documents currently known to the system. * All text documents currently known to the system.
*
* @readonly
*/ */
export let textDocuments: TextDocument[]; export let textDocuments: TextDocument[];
@ -2448,8 +2497,11 @@ declare namespace vscode {
* [open document](#workspace.onDidOpenTextDocument)-event fires. * [open document](#workspace.onDidOpenTextDocument)-event fires.
* *
* The document to open is denoted by the [uri](#Uri). Two schemes are supported: * The document to open is denoted by the [uri](#Uri). Two schemes are supported:
* * **file** a file on disk, will be rejected if the file does not exist or cannot be loaded, e.g. 'file:///Users/frodo/r.ini'. * | Scheme | Description
* * **untitled** a new file that should be saved on disk, e.g. 'untitled:/Users/frodo/new.js'. The language will be derived from the file name. * | :----- | :----
* | file | A file on disk, will be rejected if the file does not exist or cannot be loaded, e.g. 'file:///Users/frodo/r.ini'.
* | untitled | A new file that should be saved on disk, e.g. 'untitled:/Users/frodo/new.js'. The language will be derived from the file name.
*
* Uris with other schemes will make this method returned a rejected promise. * Uris with other schemes will make this method returned a rejected promise.
* *
* @param uri Identifies the resource to open. * @param uri Identifies the resource to open.
@ -2458,12 +2510,16 @@ declare namespace vscode {
export function openTextDocument(uri: Uri): Thenable<TextDocument>; export function openTextDocument(uri: Uri): Thenable<TextDocument>;
/** /**
* Like `openTextDocument(Uri.file(fileName))` * A short-hand for `openTextDocument(Uri.file(fileName))`.
*
* @see [openTextDocument](#openTextDocument)
* @param fileName A name of a file on disk
* @return A promise that resolves to a [document](#TextDocument)
*/ */
export function openTextDocument(fileName: string): Thenable<TextDocument>; export function openTextDocument(fileName: string): Thenable<TextDocument>;
/** /**
* An event that is emitted when a [text document](#TextDocument) is created. * An event that is emitted when a [text document](#TextDocument) is opened.
*/ */
export const onDidOpenTextDocument: Event<TextDocument>; export const onDidOpenTextDocument: Event<TextDocument>;
@ -2483,14 +2539,28 @@ declare namespace vscode {
export const onDidSaveTextDocument: Event<TextDocument>; export const onDidSaveTextDocument: Event<TextDocument>;
/** /**
* Get a configuration object.
* *
* When a section-identifier is provided only that part of the configuration
* is returned. Dots in the section-identifiers are interpreted as child-access,
* like `{ myExt: { setting: { doIt: true }}}` and `getConfiguration('myExt.setting.doIt') === true`.
*
*
* @param section A dot-separated identifier.
* @return The full workspace configuration or a subset.
*/ */
export function getConfiguration(section?: string): WorkspaceConfiguration; export function getConfiguration(section?: string): WorkspaceConfiguration;
// TODO: send out the new config? /**
* An event that is emitted when the [configuration](#WorkspaceConfiguration) changed.
*/
export const onDidChangeConfiguration: Event<void>; export const onDidChangeConfiguration: Event<void>;
} }
/**
* The languages namespace contains function to participate in language service features,
* like IntelliSense or diagnostics.
*/
export namespace languages { export namespace languages {
/** /**
@ -2505,7 +2575,7 @@ declare namespace vscode {
* *
* @param selector A document selector. * @param selector A document selector.
* @param document A text document. * @param document A text document.
* @return Value > 0 when the selector matches, 0 when the selector does not match. * @return A number `>0` when the selector matches and `0` when the selector does not match.
*/ */
export function match(selector: DocumentSelector, document: TextDocument): number; export function match(selector: DocumentSelector, document: TextDocument): number;
@ -2518,6 +2588,12 @@ declare namespace vscode {
export function createDiagnosticCollection(name?: string): DiagnosticCollection; export function createDiagnosticCollection(name?: string): DiagnosticCollection;
/** /**
* Register a completion provider.
*
* Multiple providers can be registered for a language. In that case providers are sorted
* by their [score](#language.match) and groups of equal score are sequentially asked for
* completion items. The process stops when one or many providers of a group return a
* result.
* *
* @param selector A selector that defines the documents this provider is applicable to. * @param selector A selector that defines the documents this provider is applicable to.
* @param provider A completion provider. * @param provider A completion provider.