Custom editor documentation

[alexr00]

Testing #99003

The webviewOptionshas no documentation comment, but the supportsMultipleEditorsPerDocument property right below it has a huge comment. It would be nice to have comment on the webviewOptions.

Looks like there's a word missing here (... instead of reading the file from this user's...):

vscode/src/vs/vscode.d.ts

Lines 7025 to 7026 in eb09996

	* If this is provided, your extension should restore the editor from the backup instead of reading the file
	* the user's workspace.

I find this to be confusing. "and the resolve(d) document is passed to resolveCustomEditor". I think it should not refer to an already resolved document, since at this point the document is not "resolved" by resolveCustomEditor. Instead, may the "returned" document?

vscode/src/vs/vscode.d.ts

Lines 7046 to 7049 in eb09996

	* `openCustomDocument` is called when the first editor for a given resource is opened, and the resolve document
	* is passed to `resolveCustomEditor`. The resolved `CustomDocument` is re-used for subsequent editor opens.
	* If all editors for a given resource are closed, the `CustomDocument` is disposed of. Opening an editor at
	* this point will trigger another call to `openCustomDocument`.

For the documentation around resolveCustomEditor and resolveCustomTextEditor, I have trouble understanding what the webviewPanel is for just by reading the comment. Perhaps consider adding something about how the webview should be used for displaying the custom editor data.

vscode/src/vs/vscode.d.ts

Lines 7059 to 7074 in eb09996

	/**
	* Resolve a custom editor for a given resource.
	*
	* This is called whenever the user opens a new editor for this `CustomEditorProvider`.
	*
	* To resolve a custom editor, the provider must fill in its initial html content and hook up all
	* the event listeners it is interested it. The provider can also hold onto the `WebviewPanel` to use later,
	* for example in a command. See [`WebviewPanel`](#WebviewPanel) for additional details.
	*
	* @param document Document for the resource being resolved.
	* @param webviewPanel Webview to resolve.
	* @param token A cancellation token that indicates the result is no longer needed.
	*
	* @return Optional thenable indicating that the custom editor has been resolved.
	*/
	resolveCustomEditor(document: T, webviewPanel: WebviewPanel, token: CancellationToken): Thenable<void> | void;

Would be good to give an example of where in the UI this would be shown:

vscode/src/vs/vscode.d.ts

Lines 6963 to 6968 in eb09996

	/**
	* Display name describing the edit.
	*
	* This is shown in the UI to users.
	*/
	readonly label?: string;

Unfinished sentence?

vscode/src/vs/vscode.d.ts

Lines 7013 to 7014 in eb09996

	* For editors for workspace resource, this destination will be in the workspace storage. The path may not
	*/

[alexr00]

Does this mean that CustomTextEditorProviders automatically allow multiple editors, or that the never do?

vscode/src/vs/vscode.d.ts

Lines 8038 to 8051 in eb09996

	/**
	* Only applies to `CustomReadonlyEditorProvider | CustomEditorProvider`.
	*
	* Indicates that the provider allows multiple editor instances to be open at the same time for
	* the same resource.
	*
	* If not set, VS Code only allows one editor instance to be open at a time for each resource. If the
	* user tries to open a second editor instance for the resource, the first one is instead moved to where
	* the second one was to be opened.
	*
	* When set, users can split and create copies of the custom editor. The custom editor must make sure it
	* can properly synchronize the states of all editor instances for a resource so that they are consistent.
	*/
	readonly supportsMultipleEditorsPerDocument?: boolean;

Reading the docs here, it talks about how a single TextDocument can have multiple webviews if you split. Sounds like that means that CustomTextEditorProviders automatically can have multiple webviews.

[alexr00]

The docs page is excellent!

[mjbvz]

Thanks for the suggestions. I believe I've addressed them all but let me know if anything in the docs is still unclear