Skip to content

Commit 7b078e1

Browse files
rebornixrebornix
authored
Merge pull request microsoft#74089 from microsoft/rr/comments
Comment API
2 parents a330f0f + 48f6cce commit 7b078e1

19 files changed

Lines changed: 929 additions & 449 deletions

‎src/vs/editor/common/modes.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1288,6 +1288,7 @@ export interface CommentThread2 {
12881288
resource: string | null;
12891289
range: IRange;
12901290
label: string;
1291+
contextValue: string | undefined;
12911292
comments: Comment[] | undefined;
12921293
onDidChangeComments: Event<Comment[] | undefined>;
12931294
collapsibleState?: CommentThreadCollapsibleState;
@@ -1326,6 +1327,7 @@ export interface CommentThread {
13261327
collapsibleState?: CommentThreadCollapsibleState;
13271328
reply?: Command;
13281329
isDisposed?: boolean;
1330+
contextValue?: string;
13291331
}
13301332

13311333
/**
@@ -1347,14 +1349,24 @@ export interface CommentReaction {
13471349
readonly canEdit?: boolean;
13481350
}
13491351

1352+
/**
1353+
* @internal
1354+
*/
1355+
export enum CommentMode {
1356+
Editing = 0,
1357+
Preview = 1
1358+
}
1359+
13501360
/**
13511361
* @internal
13521362
*/
13531363
export interface Comment {
13541364
readonly commentId: string;
1365+
readonly uniqueIdInThread?: number;
13551366
readonly body: IMarkdownString;
13561367
readonly userName: string;
13571368
readonly userIconPath?: string;
1369+
readonly contextValue?: string;
13581370
readonly canEdit?: boolean;
13591371
readonly canDelete?: boolean;
13601372
readonly selectCommand?: Command;
@@ -1363,6 +1375,7 @@ export interface Comment {
13631375
readonly isDraft?: boolean;
13641376
readonly commentReactions?: CommentReaction[];
13651377
readonly label?: string;
1378+
readonly mode?: CommentMode;
13661379
}
13671380

13681381
/**

‎src/vs/platform/actions/common/actions.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,6 +95,10 @@ export const enum MenuId {
9595
TouchBarContext,
9696
ViewItemContext,
9797
ViewTitle,
98+
CommentThreadTitle,
99+
CommentThreadActions,
100+
CommentTitle,
101+
CommentActions
98102
}
99103

100104
export interface IMenuActionOptions {

‎src/vs/vscode.d.ts‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8940,6 +8940,237 @@ declare module 'vscode' {
89408940
*/
89418941
export const onDidChange: Event<void>;
89428942
}
8943+
8944+
//#region Comments
8945+
8946+
/**
8947+
* Collapsible state of a [comment thread](#CommentThread)
8948+
*/
8949+
export enum CommentThreadCollapsibleState {
8950+
/**
8951+
* Determines an item is collapsed
8952+
*/
8953+
Collapsed = 0,
8954+
8955+
/**
8956+
* Determines an item is expanded
8957+
*/
8958+
Expanded = 1
8959+
}
8960+
8961+
/**
8962+
* Comment mode of a [comment](#Comment)
8963+
*/
8964+
export enum CommentMode {
8965+
/**
8966+
* Displays the comment editor
8967+
*/
8968+
Editing = 0,
8969+
8970+
/**
8971+
* Displays the preview of the comment
8972+
*/
8973+
Preview = 1
8974+
}
8975+
8976+
/**
8977+
* A collection of [comments](#Comment) representing a conversation at a particular range in a document.
8978+
*/
8979+
export interface CommentThread {
8980+
/**
8981+
* The uri of the document the thread has been created on.
8982+
*/
8983+
readonly resource: Uri;
8984+
8985+
/**
8986+
* The range the comment thread is located within the document. The thread icon will be shown
8987+
* at the first line of the range.
8988+
*/
8989+
range: Range;
8990+
8991+
/**
8992+
* The ordered comments of the thread.
8993+
*/
8994+
comments: ReadonlyArray<Comment>;
8995+
8996+
/**
8997+
* Whether the thread should be collapsed or expanded when opening the document.
8998+
* Defaults to Collapsed.
8999+
*/
9000+
collapsibleState: CommentThreadCollapsibleState;
9001+
9002+
/**
9003+
* Context value of the comment thread. This can be used to contribute thread specific actions.
9004+
* For example, a comment thread is given a context value as `editable`. When contributing actions to `comments/commentThread/title`
9005+
* using `menus` extension point, you can specify context value for key `commentThread` in `when` expression like `commentThread == editable`.
9006+
* ```
9007+
* "contributes": {
9008+
* "menus": {
9009+
* "comments/commentThread/title": [
9010+
* {
9011+
* "command": "extension.deleteCommentThread",
9012+
* "when": "commentThread == editable"
9013+
* }
9014+
* ]
9015+
* }
9016+
* }
9017+
* ```
9018+
* This will show action `extension.deleteCommentThread` only for comment threads with `contextValue` is `editable`.
9019+
*/
9020+
contextValue?: string;
9021+
9022+
/**
9023+
* The optional human-readable label describing the [Comment Thread](#CommentThread)
9024+
*/
9025+
label?: string;
9026+
9027+
/**
9028+
* Dispose this comment thread.
9029+
*
9030+
* Once disposed, this comment thread will be removed from visible editors and Comment Panel when approriate.
9031+
*/
9032+
dispose(): void;
9033+
}
9034+
9035+
/**
9036+
* Author information of a [comment](#Comment)
9037+
*/
9038+
export interface CommentAuthorInformation {
9039+
/**
9040+
* The display name of the author of the comment
9041+
*/
9042+
name: string;
9043+
9044+
/**
9045+
* The optional icon path for the author
9046+
*/
9047+
iconPath?: Uri;
9048+
}
9049+
9050+
/**
9051+
* A comment is displayed within the editor or the Comments Panel, depending on how it is provided.
9052+
*/
9053+
export interface Comment {
9054+
/**
9055+
* The human-readable comment body
9056+
*/
9057+
body: string | MarkdownString;
9058+
9059+
/**
9060+
* [Comment mode](#CommentMode) of the comment
9061+
*/
9062+
mode: CommentMode;
9063+
9064+
/**
9065+
* The [author information](#CommentAuthorInformation) of the comment
9066+
*/
9067+
author: CommentAuthorInformation;
9068+
9069+
/**
9070+
* Context value of the comment. This can be used to contribute comment specific actions.
9071+
* For example, a comment is given a context value as `editable`. When contributing actions to `comments/comment/title`
9072+
* using `menus` extension point, you can specify context value for key `comment` in `when` expression like `comment == editable`.
9073+
* ```
9074+
* "contributes": {
9075+
* "menus": {
9076+
* "comments/comment/title": [
9077+
* {
9078+
* "command": "extension.deleteComment",
9079+
* "when": "comment == editable"
9080+
* }
9081+
* ]
9082+
* }
9083+
* }
9084+
* ```
9085+
* This will show action `extension.deleteComment` only for comments with `contextValue` is `editable`.
9086+
*/
9087+
contextValue?: string;
9088+
9089+
/**
9090+
* Optional label describing the [Comment](#Comment)
9091+
* Label will be rendered next to authorName if exists.
9092+
*/
9093+
label?: string;
9094+
}
9095+
9096+
/**
9097+
* Command argument for actions registered in `comments/commentThread/actions`.
9098+
*/
9099+
export interface CommentReply {
9100+
/**
9101+
* The active [comment thread](#CommentThread)
9102+
*/
9103+
thread: CommentThread;
9104+
9105+
/**
9106+
* The value in the comment editor
9107+
*/
9108+
text: string;
9109+
}
9110+
9111+
/**
9112+
* Commenting range provider for a [comment controller](#CommentController).
9113+
*/
9114+
export interface CommentingRangeProvider {
9115+
/**
9116+
* Provide a list of ranges which allow new comment threads creation or null for a given document
9117+
*/
9118+
provideCommentingRanges(document: TextDocument, token: CancellationToken): ProviderResult<Range[]>;
9119+
}
9120+
9121+
/**
9122+
* A comment controller is able to provide [comments](#CommentThread) support to the editor and
9123+
* provide users various ways to interact with comments.
9124+
*/
9125+
export interface CommentController {
9126+
/**
9127+
* The id of this comment controller.
9128+
*/
9129+
readonly id: string;
9130+
9131+
/**
9132+
* The human-readable label of this comment controller.
9133+
*/
9134+
readonly label: string;
9135+
9136+
/**
9137+
* Optional commenting range provider. Provide a list [ranges](#Range) which support commenting to any given resource uri.
9138+
*
9139+
* If not provided, users can leave comments in any document opened in the editor.
9140+
*/
9141+
commentingRangeProvider?: CommentingRangeProvider;
9142+
9143+
/**
9144+
* Create a [comment thread](#CommentThread). The comment thread will be displayed in visible text editors (if the resource matches)
9145+
* and Comments Panel once created.
9146+
*
9147+
* @param resource The uri of the document the thread has been created on.
9148+
* @param range The range the comment thread is located within the document.
9149+
* @param comments The ordered comments of the thread.
9150+
*/
9151+
createCommentThread(uri: Uri, range: Range, comments: Comment[]): CommentThread;
9152+
9153+
/**
9154+
* Dispose this comment controller.
9155+
*
9156+
* Once disposed, all [comment threads](#CommentThread) created by this comment controller will also be removed from the editor
9157+
* and Comments Panel.
9158+
*/
9159+
dispose(): void;
9160+
}
9161+
9162+
namespace comments {
9163+
/**
9164+
* Creates a new [comment controller](#CommentController) instance.
9165+
*
9166+
* @param id An `id` for the comment controller.
9167+
* @param label A human-readable string for the comment controller.
9168+
* @return An instance of [comment controller](#CommentController).
9169+
*/
9170+
export function createCommentController(id: string, label: string): CommentController;
9171+
}
9172+
9173+
//#endregion
89439174
}
89449175

89459176
/**

0 commit comments

Comments
 (0)