Comments Provider API

[RMacfarlane]

Introduces the concept of comment threads and comments, and adds two providers an extension can register. One for on-demand comments when an editor is opened, rendered in the editor, and one to display all comments in the workspace and allow navigation.

interface CommentInfo {
		threads: CommentThread[];
		commentingRanges?: Range[];
	}

	export enum CommentThreadCollapsibleState {
		/**
		 * Determines an item is collapsed
		 */
		Collapsed = 0,
		/**
		 * Determines an item is expanded
		 */
		Expanded = 1
	}

	interface CommentThread {
		threadId: string;
		resource: Uri;
		range: Range;
		comments: Comment[];
		collapsibleState?: CommentThreadCollapsibleState;
	}

	interface Comment {
		commentId: string;
		body: MarkdownString;
		userName: string;
		gravatar: string;
		command?: Command;
	}

	export interface CommentThreadChangedEvent {
		/**
		 * Added comment threads.
		 */
		readonly added: CommentThread[];

		/**
		 * Removed comment threads.
		 */
		readonly removed: CommentThread[];

		/**
		 * Changed comment threads.
		 */
		readonly changed: CommentThread[];
	}

	interface DocumentCommentProvider {
		provideDocumentComments(document: TextDocument, token: CancellationToken): Promise<CommentInfo>;
		createNewCommentThread?(document: TextDocument, range: Range, text: string, token: CancellationToken): Promise<CommentThread>;
		replyToCommentThread?(document: TextDocument, range: Range, commentThread: CommentThread, text: string, token: CancellationToken): Promise<CommentThread>;
		onDidChangeCommentThreads?: Event<CommentThreadChangedEvent>;
	}

	interface WorkspaceCommentProvider {
		provideWorkspaceComments(token: CancellationToken): Promise<CommentThread[]>;
		createNewCommentThread?(document: TextDocument, range: Range, text: string, token: CancellationToken): Promise<CommentThread>;
		replyToCommentThread?(document: TextDocument, range: Range, commentThread: CommentThread, text: string, token: CancellationToken): Promise<CommentThread>;

		onDidChangeCommentThreads?: Event<CommentThreadChangedEvent>;
	}

[mgood]

This is exciting. I had started prototyping a code review extension using "info" diagnostic messages to display comments, but this will be much better.

A couple things I'd find useful:

• "draft" state (or similar) for replies to support comments that have been saved, but not yet published
• marking threads as "done" or "completed"

We use Phabricator which supports these features, but Github code reviews has something very similar so that could be a good candidate to look at for features.

Or maybe instead of adding specific support this could be implemented by including a way to include annotations for the thread "status", as well as a menu of actions that can be performed on the thread.

On a related note, I was initially going to use the Language Server Protocol to provide the Diagnostics for my extension. Once this has stabilized I would also find it interesting if the Language Server was extended to provide a commenting API like this as well to standardize support across other editors.

[mgood]

Another wishlist item would be for the "Reply" to use a rich editor instead of the basic text field shown in the screenshot from the release notes. To support that the comment provider API should have a way to indicate the syntax language for the reply. This would enable some nicer support for the markup language supported by the comment extension. In addition to basics like general Markdown syntax I'd like to have the ability to provide other language features like completions for things like @username.

[RMacfarlane]

@mgood These are great suggestions, and things I'd also like to see in the API.

There's definitely a need for having some kind of "status" associated with a thread, VSTS also has a concept of marking threads as "resolved", "won't fix", etc, and GitHub has also recently introduced a way of resolving conversations.

As you said, "draft" state is also common between various code review tools. Username completions are, too. There's also a similar concept of either liking or reacting to other's comments.

The next step I'm going to start work on is providing a way to edit and delete comments: #58078

[nicksnyder]

I am experimenting with the proposed API and am confused how to get createNewCommentThread to get called (I dug through the code and didn't see a way).

Ideally, I would like my extension to be able to expose a command that opens the UI to create a new comment in a code file.

Got it. Needed to return commentingRanges!

[nicksnyder]

Why does the Comment interface have a field called gravatar when it is just an image url?

[RMacfarlane]

@nicksnyder it should be renamed to something like userIcon

[pprice]

I've started looking into the APIs for use with phabricator.

I'd like to echo the need for:

• Comment states (done / not done); given the breadth of code-review workflows, maybe this could be an extension specified "list" to pick from? In phabriactor this is actually boolean state, but a list would be more flexible.
• Draft comments - phabricator's workflow is to publish comments as a single action. This could also be done with a state api, but a state that is not under controlled.
• Comment formats - Support different comment input formats, API expects markdown today, phabricator uses remarkup.

Some nice to haves:

• Comment completions - Ability to provide customization to the comment input "completions" (user mentions, macros, phabricator style object links)
• Comment previews - Ability to render comment markup inline when editing (just like on github)

That said, I think I can make a fair bit of headway with what is here today.

[rebornix]

@pprice thanks Phil, your suggestions are really helpful and they are on our radar.

Comment completion is probably an easy one as we use a specific scheme for the comment editor inside the editor, so an extension can register a suggestion provider for it. We didn't finalize the scheme yet but that's the way we'll go.

Speaking of comment format, it's a bit complex but we can provide similar APIs as above, a specific preview provider or something similar, it can help with both the final rendering and comment preview.

We need to think more about how to introduce the comment state concept into the API, like you said it's like an enum but may vary in different comment systems. Drafts of comments (or pending reviews in some systems) may involve some UI change and @RMacfarlane has some insights into it already #53598 (comment) .

[otakustay]

I'm wondering how we can utilize the onDidChangeCommentThreads event to modify comment threads on a certain document, the CommentThreadChangedEvent interface does not contain a document property, the only added, changed and removed properties are insufficient to tell which document should respond to changes.