@theia/plugin 1.67.0-next.3 → 1.67.0-next.56

package/README.md

@@ -761,7 +761,7 @@ function provideRanges(document: theia.TextDocument): theia.ProviderResult<theia
 
 ## Additional Information
 
-- [API documentation for `@theia/plugin`](https://eclipse-theia.github.io/theia/docs/next/modules/plugin.html)
+- [API documentation for `@theia/plugin`](https://eclipse-theia.github.io/theia/docs/next/modules/_theia_plugin.html)
 - [Theia - GitHub](https://github.com/eclipse-theia/theia)
 - [Theia - Website](https://theia-ide.org/)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theia/plugin",
-  "version": "1.67.0-next.3+7946ca874",
+  "version": "1.67.0-next.56+d8f18cc386c",
   "description": "Theia - Plugin API",
   "types": "./src/theia.d.ts",
   "publishConfig": {
@@ -32,5 +32,5 @@
   "nyc": {
     "extends": "../../configs/nyc.json"
   },
-  "gitHead": "7946ca874b04e6249d883e9a586f193194df1365"
+  "gitHead": "d8f18cc386c45a736cd193d42eab02c8f64c6b10"
 }

package/src/theia.d.ts

@@ -3204,6 +3204,8 @@ export module '@theia/plugin' {
          * @param commandLine The command line to execute, this is the exact text that will be sent
          * to the terminal.
          *
+         * @throws When run on a terminal doesn't support this API, such as task terminals.
+         *
          * @example
          * // Execute a command in a terminal immediately after being created
          * const myTerm = window.createTerminal();
@@ -11478,6 +11480,10 @@ export module '@theia/plugin' {
      * semantic tokens.
      */
     export interface DocumentRangeSemanticTokensProvider {
+        /**
+         * An optional event to signal that the semantic tokens from this provider have changed.
+         */
+        onDidChangeSemanticTokens?: Event<void>;
         /**
          * @see {@link DocumentSemanticTokensProvider.provideDocumentSemanticTokens provideDocumentSemanticTokens}.
          */
@@ -15028,10 +15034,17 @@ export module '@theia/plugin' {
         readonly id: string;
 
         /**
-         * The access token.
+         * The access token. This token should be used to authenticate requests to a service. Popularized by OAuth.
+         * @reference https://oauth.net/2/access-tokens/
          */
         readonly accessToken: string;
 
+        /**
+         * The ID token. This token contains identity information about the user. Popularized by OpenID Connect.
+         * @reference https://openid.net/specs/openid-connect-core-1_0.html#IDToken
+         */
+        readonly idToken?: string;
+
         /**
          * The account associated with the session.
          */
@@ -18629,7 +18642,7 @@ export module '@theia/plugin' {
          * @param name The optional name of a user for the message.
          * @stubbed
          */
-        static User(content: string | Array<LanguageModelTextPart | LanguageModelToolResultPart>, name?: string): LanguageModelChatMessage;
+        static User(content: string | Array<LanguageModelTextPart | LanguageModelToolResultPart | LanguageModelDataPart>, name?: string): LanguageModelChatMessage;
 
         /**
          * Utility to create a new assistant message.
@@ -18638,7 +18651,7 @@ export module '@theia/plugin' {
          * @param name The optional name of a user for the message.
          * @stubbed
          */
-        static Assistant(content: string | Array<(LanguageModelTextPart | LanguageModelToolCallPart)>, name?: string): LanguageModelChatMessage;
+        static Assistant(content: string | Array<LanguageModelTextPart | LanguageModelToolCallPart | LanguageModelDataPart>, name?: string): LanguageModelChatMessage;
 
         /**
          * The role of this message.
@@ -18674,13 +18687,13 @@ export module '@theia/plugin' {
      * The various message types which a {@linkcode LanguageModelChatProvider} can emit in the chat response stream
      * @stubbed
      */
-    export type LanguageModelResponsePart = LanguageModelTextPart | LanguageModelToolResultPart | LanguageModelToolCallPart;
+    export type LanguageModelResponsePart = LanguageModelTextPart | LanguageModelToolResultPart | LanguageModelToolCallPart | LanguageModelDataPart;
 
     /**
      * The various message types which can be sent via {@linkcode LanguageModelChat.sendRequest } and processed by a {@linkcode LanguageModelChatProvider}
      * @stubbed
      */
-    export type LanguageModelInputPart = LanguageModelTextPart | LanguageModelToolResultPart | LanguageModelToolCallPart;
+    export type LanguageModelInputPart = LanguageModelTextPart | LanguageModelToolResultPart | LanguageModelToolCallPart | LanguageModelDataPart;
 
     /**
      * Represents a language model response.
@@ -18722,7 +18735,7 @@ export module '@theia/plugin' {
          * ```
          * @stubbed
          */
-        stream: AsyncIterable<LanguageModelTextPart | LanguageModelToolCallPart | unknown>;
+        stream: AsyncIterable<LanguageModelTextPart | LanguageModelToolCallPart | LanguageModelDataPart | unknown>;
 
         /**
          * This is equivalent to filtering everything except for text parts from a {@link LanguageModelChatResponse.stream}.
@@ -19512,14 +19525,14 @@ export module '@theia/plugin' {
          * The value of the tool result.
          * @stubbed
          */
-        content: Array<LanguageModelTextPart | LanguageModelPromptTsxPart | unknown>;
+        content: Array<LanguageModelTextPart | LanguageModelPromptTsxPart | LanguageModelDataPart | unknown>;
 
         /**
          * @param callId The ID of the tool call.
          * @param content The content of the tool result.
          * @stubbed
          */
-        constructor(callId: string, content: Array<(LanguageModelTextPart | LanguageModelPromptTsxPart | unknown)>);
+        constructor(callId: string, content: Array<LanguageModelTextPart | LanguageModelPromptTsxPart | LanguageModelDataPart | unknown>);
     }
 
     /**
@@ -19572,14 +19585,71 @@ export module '@theia/plugin' {
          * @see {@link lm.invokeTool}.
          * @stubbed
          */
-        content: Array<(LanguageModelTextPart | LanguageModelPromptTsxPart | unknown)>;
+        content: Array<LanguageModelTextPart | LanguageModelPromptTsxPart | LanguageModelDataPart | unknown>;
 
         /**
          * Create a LanguageModelToolResult
          * @param content A list of tool result content parts
          * @stubbed
          */
-        constructor(content: Array<(LanguageModelTextPart | LanguageModelPromptTsxPart)>);
+        constructor(content: Array<LanguageModelTextPart | LanguageModelPromptTsxPart | LanguageModelDataPart | unknown>);
+    }
+
+    /**
+     * A language model response part containing arbitrary data. Can be used in {@link LanguageModelChatResponse responses},
+     * {@link LanguageModelChatMessage chat messages}, {@link LanguageModelToolResult tool results}, and other language model interactions.
+     * @stubbed
+     */
+    export class LanguageModelDataPart {
+        /**
+         * Create a new {@linkcode LanguageModelDataPart} for an image.
+         * @param data Binary image data
+         * @param mime The MIME type of the image. Common values are `image/png` and `image/jpeg`.
+         * @stubbed
+         */
+        static image(data: Uint8Array, mime: string): LanguageModelDataPart;
+
+        /**
+         * Create a new {@linkcode LanguageModelDataPart} for a json.
+         *
+         * *Note* that this function is not expecting "stringified JSON" but
+         * an object that can be stringified. This function will throw an error
+         * when the passed value cannot be JSON-stringified.
+         * @param value  A JSON-stringifyable value.
+         * @param mime Optional MIME type, defaults to `application/json`
+         * @stubbed
+         */
+        static json(value: any, mime?: string): LanguageModelDataPart;
+
+        /**
+         * Create a new {@linkcode LanguageModelDataPart} for text.
+         *
+         * *Note* that an UTF-8 encoder is used to create bytes for the string.
+         * @param value Text data
+         * @param mime The MIME type if any. Common values are `text/plain` and `text/markdown`.
+         * @stubbed
+         */
+        static text(value: string, mime?: string): LanguageModelDataPart;
+
+        /**
+         * The mime type which determines how the data property is interpreted.
+         * @stubbed
+         */
+        mimeType: string;
+
+        /**
+         * The byte data for this part.
+         * @stubbed
+         */
+        data: Uint8Array;
+
+        /**
+         * Construct a generic data part with the given content.
+         * @param data The byte data for this part.
+         * @param mimeType The mime type of the data.
+         * @stubbed
+         */
+        constructor(data: Uint8Array, mimeType: string);
     }
 
     /**

package/src/theia.proposed.notebookKernelSource.d.ts

@@ -18,6 +18,7 @@
  *  Copyright (c) Microsoft Corporation. All rights reserved.
  *  Licensed under the MIT License. See License.txt in the project root for license information.
  *--------------------------------------------------------------------------------------------*/
+// code copied and modified from https://github.com/microsoft/vscode/blob/1.106.1/src/vscode-dts/vscode.proposed.notebookKernelSource.d.ts
 
 export module '@theia/plugin' {
     export interface NotebookControllerDetectionTask {
@@ -41,7 +42,7 @@ export module '@theia/plugin' {
         /**
          * An optional event to signal that the kernel source actions have changed.
          */
-        onDidChangeNotebookKernelSourceActions?: Event<void>;
+        readonly onDidChangeNotebookKernelSourceActions?: Event<void>;
         /**
          * Provide kernel source actions
          */

package/src/theia.proposed.terminalCompletionProvider.d.ts

@@ -18,7 +18,7 @@
  *  Copyright (c) Microsoft Corporation. All rights reserved.
  *  Licensed under the MIT License. See License.txt in the project root for license information.
  *--------------------------------------------------------------------------------------------*/
-// code copied and modified from https://github.com/microsoft/vscode/blob/1.105.0/src/vscode-dts/vscode.proposed.terminalCompletionProvider.d.ts
+// code copied and modified from https://github.com/microsoft/vscode/blob/1.106.1/src/vscode-dts/vscode.proposed.terminalCompletionProvider.d.ts
 
 export module '@theia/plugin' {
 
@@ -31,13 +31,13 @@ export module '@theia/plugin' {
      * {@link TerminalCompletionList} describing completions for the current command line.
      *
      * @example <caption>Simple provider returning a single completion</caption>
-     * window.registerTerminalCompletionProvider('extension-provider-id', {
+     * window.registerTerminalCompletionProvider({
      *  provideTerminalCompletions(terminal, context) {
-     *      return [{ label: '--help', replacementIndex: Math.max(0, context.cursorPosition - 2), replacementLength: 2 }];
+     *      return [{ label: '--help', replacementRange: [Math.max(0, context.cursorPosition - 2), context.cursorPosition] }];
      *  }
      * });
      */
-    export interface TerminalCompletionProvider<T extends TerminalCompletionItem> {
+    export interface TerminalCompletionProvider<T extends TerminalCompletionItem = TerminalCompletionItem> {
         /**
          * Provide completions for the given terminal and context.
          * @param terminal The terminal for which completions are being provided.
@@ -54,8 +54,7 @@ export module '@theia/plugin' {
      * @example <caption>Completion item for `ls -|`</caption>
      * const item = {
      *  label: '-A',
-     *  replacementIndex: 3,
-     *  replacementLength: 1,
+     *  replacementRange: [3, 4], // replace the single character at index 3
      *  detail: 'List all entries except for . and .. (always set for the super-user)',
      *  kind: TerminalCompletionItemKind.Flag
      * };
@@ -63,21 +62,18 @@ export module '@theia/plugin' {
      * The fields on a completion item describe what text should be shown to the user
      * and which portion of the command line should be replaced when the item is accepted.
      */
-    export interface TerminalCompletionItem {
+    export class TerminalCompletionItem {
         /**
          * The label of the completion.
          */
         label: string | CompletionItemLabel;
 
         /**
-         * The index of the start of the range to replace.
+         * The range in the command line to replace when the completion is accepted. Defined
+         * as a tuple where the first entry is the inclusive start index and the second entry is the
+         * exclusive end index.
          */
-        replacementIndex: number;
-
-        /**
-         * The length of the range to replace.
-         */
-        replacementLength: number;
+        replacementRange: readonly [number, number];
 
         /**
          * The completion's detail which appears on the right of the list.
@@ -90,9 +86,22 @@ export module '@theia/plugin' {
         documentation?: string | MarkdownString;
 
         /**
-         * The completion's kind. Note that this will map to an icon.
+         * The completion's kind. Note that this will map to an icon. If no kind is provided, a generic icon representing plaintext will be provided.
          */
         kind?: TerminalCompletionItemKind;
+
+        /**
+         * Creates a new terminal completion item.
+         *
+         * @param label The label of the completion.
+         * @param replacementRange The inclusive start and exclusive end index of the text to replace.
+         * @param kind The completion's kind.
+         */
+        constructor(
+            label: string | CompletionItemLabel,
+            replacementRange: readonly [number, number],
+            kind?: TerminalCompletionItemKind
+        );
     }
 
     /**
@@ -100,85 +109,127 @@ export module '@theia/plugin' {
      *
      * The kind is used to render an appropriate icon in the suggest list and to convey the semantic
      * meaning of the suggestion (file, folder, flag, commit, branch, etc.).
-     *
      */
     export enum TerminalCompletionItemKind {
+        /**
+         * A file completion item.
+         * Example: `README.md`
+         */
         File = 0,
+        /**
+         * A folder completion item.
+         * Example: `src/`
+         */
         Folder = 1,
+        /**
+         * A method completion item.
+         * Example: `git commit`
+         */
         Method = 2,
+        /**
+         * An alias completion item.
+         * Example: `ll` as an alias for `ls -l`
+         */
         Alias = 3,
+        /**
+         * An argument completion item.
+         * Example: `origin` in `git push origin main`
+         */
         Argument = 4,
+        /**
+         * An option completion item. An option value is expected to follow.
+         * Example: `--locale` in `code --locale en`
+         */
         Option = 5,
+        /**
+         * The value of an option completion item.
+         * Example: `en-US` in `code --locale en-US`
+         */
         OptionValue = 6,
+        /**
+         * A flag completion item.
+         * Example: `--amend` in `git commit --amend`
+         */
         Flag = 7,
+        /**
+         * A symbolic link file completion item.
+         * Example: `link.txt` (symlink to a file)
+         */
         SymbolicLinkFile = 8,
+        /**
+         * A symbolic link folder completion item.
+         * Example: `node_modules/` (symlink to a folder)
+         */
         SymbolicLinkFolder = 9,
-        Commit = 10,
-        Branch = 11,
-        Tag = 12,
-        Stash = 13,
-        Remote = 14,
+        /**
+         * A source control commit completion item.
+         * Example: `abc1234` (commit hash)
+         */
+        ScmCommit = 10,
+        /**
+         * A source control branch completion item.
+         * Example: `main`
+         */
+        ScmBranch = 11,
+        /**
+         * A source control tag completion item.
+         * Example: `v1.0.0`
+         */
+        ScmTag = 12,
+        /**
+         * A source control stash completion item.
+         * Example: `stash@{0}`
+         */
+        ScmStash = 13,
+        /**
+         * A source control remote completion item.
+         * Example: `origin`
+         */
+        ScmRemote = 14,
+        /**
+         * A pull request completion item.
+         * Example: `#42 Add new feature`
+         */
         PullRequest = 15,
+        /**
+         * A closed pull request completion item.
+         * Example: `#41 Fix bug (closed)`
+         */
         PullRequestDone = 16,
     }
 
     /**
      * Context information passed to {@link TerminalCompletionProvider.provideTerminalCompletions}.
      *
-     * It contains the full command line, the current cursor position, and a flag indicating whether
-     * fallback completions are allowed when the exact completion type cannot be determined.
+     * It contains the full command line and the current cursor position.
      */
     export interface TerminalCompletionContext {
         /**
          * The complete terminal command line.
          */
-        commandLine: string;
+        readonly commandLine: string;
         /**
          * The index of the cursor in the command line.
          */
-        cursorPosition: number;
-        /**
-         * Whether completions should be provided when it is not clear to what type of completion is
-         * well known.
-         */
-        allowFallbackCompletions: boolean;
-    }
-
-    export namespace window {
-        /**
-         * Register a completion provider for terminals.
-         * @param id The unique identifier of the terminal provider, used as a settings key and shown in the information hover of the suggest widget.
-         * @param provider The completion provider.
-         * @returns A {@link Disposable} that unregisters this provider when being disposed.
-         *
-         * @example <caption>Register a provider for an extension</caption>
-         * window.registerTerminalCompletionProvider('extension-provider-id', {
-         *  provideTerminalCompletions(terminal, context) {
-         *      return new TerminalCompletionList([
-         *          { label: '--version', replacementIndex: Math.max(0, context.cursorPosition - 2), replacementLength: 2 }
-         *      ]);
-         *  }
-         * });
-         */
-        export function registerTerminalCompletionProvider<T extends TerminalCompletionItem>(
-            id: string, provider: TerminalCompletionProvider<T>, ...triggerCharacters: string[]): Disposable;
+        readonly cursorIndex: number;
     }
 
     /**
      * Represents a collection of {@link TerminalCompletionItem completion items} to be presented
-     * in the terminal.
+     * in the terminal plus {@link TerminalCompletionList.resourceOptions} which indicate
+     * which file and folder resources should be requested for the terminal's cwd.
      *
      * @example <caption>Create a completion list that requests files for the terminal cwd</caption>
      * const list = new TerminalCompletionList([
-     *  { label: 'ls', replacementIndex: 0, replacementLength: 0, kind: TerminalCompletionItemKind.Method }
-     * ], { filesRequested: true, cwd: Uri.file('/home/user') });
+     *  { label: 'ls', replacementRange: [0, 0], kind: TerminalCompletionItemKind.Method }
+     * ], { showFiles: true, cwd: Uri.file('/home/user') });
      */
     export class TerminalCompletionList<T extends TerminalCompletionItem = TerminalCompletionItem> {
 
         /**
          * Resources that should be shown in the completions list for the cwd of the terminal.
          */
-        resourceRequestConfig?: TerminalResourceRequestConfig;
+        resourceOptions?: TerminalCompletionResourceOptions;
 
         /**
          * The completion items.
@@ -189,9 +240,9 @@ export module '@theia/plugin' {
          * Creates a new completion list.
          *
          * @param items The completion items.
-         * @param resourceRequestConfig Indicates which resources should be shown as completions for the cwd of the terminal.
+         * @param resourceOptions Indicates which resources should be shown as completions for the cwd of the terminal.
          */
-        constructor(items?: T[], resourceRequestConfig?: TerminalResourceRequestConfig);
+        constructor(items: T[], resourceOptions?: TerminalCompletionResourceOptions);
     }
 
     /**
@@ -200,22 +251,52 @@ export module '@theia/plugin' {
      * When a provider indicates that it wants file/folder resources, the terminal will surface completions for files and
      * folders that match {@link globPattern} from the provided {@link cwd}.
      */
-    export interface TerminalResourceRequestConfig {
+    export interface TerminalCompletionResourceOptions {
         /**
          * Show files as completion items.
          */
-        filesRequested?: boolean;
+        showFiles: boolean;
         /**
          * Show folders as completion items.
          */
-        foldersRequested?: boolean;
+        showDirectories: boolean;
         /**
-         * A {@link GlobPattern glob pattern} that controls which files suggest should surface.
+         * A glob pattern string that controls which files suggest should surface. Note that this will only apply if {@param showFiles} or {@param showDirectories} is set to true.
          */
-        globPattern?: GlobPattern;
+        globPattern?: string;
         /**
          * The cwd from which to request resources.
          */
         cwd: Uri;
     }
+
+    export namespace window {
+        /**
+         * Register a completion provider for terminals.
+         * @param provider The completion provider.
+         * @param triggerCharacters Optional characters that trigger completion. When any of these characters is typed,
+         * the completion provider will be invoked. For example, passing `'-'` would cause the provider to be invoked
+         * whenever the user types a dash character.
+         * @returns A {@link Disposable} that unregisters this provider when being disposed.
+         *
+         * @example <caption>Register a provider for an extension</caption>
+         * window.registerTerminalCompletionProvider({
+         *  provideTerminalCompletions(terminal, context) {
+         *      return new TerminalCompletionList([
+         *          { label: '--version', replacementRange: [Math.max(0, context.cursorPosition - 2), context.cursorPosition] }
+         *      ]);
+         *  }
+         * });
+         *
+         * @example <caption>Register a provider with trigger characters</caption>
+         * window.registerTerminalCompletionProvider({
+         *  provideTerminalCompletions(terminal, context) {
+         *      return new TerminalCompletionList([
+         *          { label: '--help', replacementRange: [Math.max(0, context.cursorPosition - 2), context.cursorPosition] }
+         *      ]);
+         *  }
+         * }, '-');
+         */
+        export function registerTerminalCompletionProvider<T extends TerminalCompletionItem>(provider: TerminalCompletionProvider<T>, ...triggerCharacters: string[]): Disposable;
+    }
 }

package/src/theia.proposed.timeline.d.ts

@@ -18,10 +18,12 @@
  *  Copyright (c) Microsoft Corporation. All rights reserved.
  *  Licensed under the MIT License. See License.txt in the project root for license information.
  *--------------------------------------------------------------------------------------------*/
-// code copied and modified from https://github.com/microsoft/vscode/blob/1.77.0/src/vscode-dts/vscode.proposed.timeline.d.ts
+// code copied and modified from https://github.com/microsoft/vscode/blob/1.106.1/src/vscode-dts/vscode.proposed.timeline.d.ts
 
 export module '@theia/plugin' {
 
+    // https://github.com/microsoft/vscode/issues/84297
+
     export class TimelineItem {
         /**
          * A timestamp (in milliseconds since 1 January 1970 00:00:00) for when the timeline item occurred.
@@ -41,7 +43,7 @@ export module '@theia/plugin' {
         id?: string;
 
         /**
-         * The icon path or [ThemeIcon](#ThemeIcon) for the timeline item.
+         * The icon path or {@link ThemeIcon} for the timeline item.
          */
         iconPath?: Uri | { light: Uri; dark: Uri } | ThemeIcon;
 
@@ -53,10 +55,10 @@ export module '@theia/plugin' {
         /**
          * The tooltip text when you hover over the timeline item.
          */
-        detail?: string;
+        tooltip?: string | MarkdownString | undefined;
 
         /**
-         * The [command](#Command) that should be executed when the timeline item is selected.
+         * The {@link Command} that should be executed when the timeline item is selected.
          */
         command?: Command;
 
@@ -65,14 +67,16 @@ export module '@theia/plugin' {
          * For example, a timeline item is given a context value as `commit`. When contributing actions to `timeline/item/context`
          * using `menus` extension point, you can specify context value for key `timelineItem` in `when` expression like `timelineItem == commit`.
          * ```
-         * "contributes": {
-         *   "menus": {
-         *     "timeline/item/context": [{
-         *       "command": "extension.copyCommitId",
-         *       "when": "timelineItem == commit"
-         *      }]
-         *   }
-         * }
+         *  "contributes": {
+         *      "menus": {
+         *          "timeline/item/context": [
+         *              {
+         *                  "command": "extension.copyCommitId",
+         *                  "when": "timelineItem == commit"
+         *              }
+         *          ]
+         *      }
+         *  }
          * ```
          * This will show the `extension.copyCommitId` action only for items where `contextValue` is `commit`.
          */
@@ -92,7 +96,7 @@ export module '@theia/plugin' {
 
     export interface TimelineChangeEvent {
         /**
-         * The [uri](#Uri) of the resource for which the timeline changed.
+         * The {@link Uri} of the resource for which the timeline changed.
          */
         uri: Uri;
 
@@ -109,10 +113,10 @@ export module '@theia/plugin' {
              * Use `undefined` to signal that there are no more items to be returned.
              */
             readonly cursor: string | undefined;
-        }
+        };
 
         /**
-         * An array of [timeline items](#TimelineItem).
+         * An array of {@link TimelineItem timeline items}.
          */
         readonly items: readonly TimelineItem[];
     }
@@ -135,7 +139,7 @@ export module '@theia/plugin' {
          * An optional event to signal that the timeline for a source has changed.
          * To signal that the timeline for all resources (uris) has changed, do not pass any argument or pass `undefined`.
          */
-        onDidChange?: Event<TimelineChangeEvent | undefined>;
+        readonly onDidChange?: Event<TimelineChangeEvent | undefined>;
 
         /**
          * An identifier of the source of the timeline items. This can be used to filter sources.
@@ -148,12 +152,12 @@ export module '@theia/plugin' {
         readonly label: string;
 
         /**
-         * Provide [timeline items](#TimelineItem) for a [Uri](#Uri).
+         * Provide {@link TimelineItem timeline items} for a {@link Uri}.
          *
-         * @param uri The [uri](#Uri) of the file to provide the timeline for.
+         * @param uri The {@link Uri} of the file to provide the timeline for.
          * @param options A set of options to determine how results should be returned.
          * @param token A cancellation token.
-         * @return The [timeline result](#TimelineResult) or a thenable that resolves to such. The lack of a result
+         * @return The {@link TimelineResult timeline result} or a thenable that resolves to such. The lack of a result
          * can be signaled by returning `undefined`, `null`, or an empty array.
          */
         provideTimeline(uri: Uri, options: TimelineOptions, token: CancellationToken): ProviderResult<Timeline>;
@@ -169,7 +173,7 @@ export module '@theia/plugin' {
          *
          * @param scheme A scheme or schemes that defines which documents this provider is applicable to. Can be `*` to target all documents.
          * @param provider A timeline provider.
-         * @return A [disposable](#Disposable) that unregisters this provider when being disposed.
+         * @return A {@link Disposable} that unregisters this provider when being disposed.
          */
         export function registerTimelineProvider(scheme: string | string[], provider: TimelineProvider): Disposable;
     }