Vscode: Collecting Feedback for Extensibility Documentation

[octref]

As some of you might have noticed in the freshly baked September Iteration Plan, one of our focus this month is extensibility documentation. Which comprise of:

• The "Extension Authoring" and "Extensibility Reference" sections on our doc page: https://code.visualstudio.com/docs
• https://github.com/Microsoft/vscode-extension-samples

Some of the issues we are already aware of:

• API Reference is hard to use: https://code.visualstudio.com/docs/extensionAPI/vscode-api.
• Some topics (for example, Proposed API) have information scattered throughout release notes, wiki and GitHub issues.
• The API sections on the website could improve its organization to have better topic categories & depth progression.

We'll try to address those issues. But we also want to hear from you, the extension authors.

While you are trying to write VS Code extensions, which doc page is hard to understand? What are the issues you run into? On what topic were you unable to find useful information? How can we make the process more enjoyable for you?

[nathfreder]

It would be great to have code examples!

[octref]

@nathfreder We do have samples: https://github.com/Microsoft/vscode-extension-samples. Did you have trouble finding that repo?

[fabiospampinato]

Some topics (for example, Proposed API) have information scattered throughout release notes, wiki and GitHub issues.

Fixing this would probably be one of the biggest improvements for me.

Some suggestions:

• Too much stuff is undocumented:
  
  
  
  • I think there's still no documentation on the $(icon) thing for inserting icons https://github.com/Microsoft/vscode-docs/issues/1094. What icons are supported? Where can someone use this syntax? I don't think this is documented.
  
  
  • Today I've learned one can write $(icon~spin) to have a rotating icon.
  
  
  • The syntax supported in when clauses is also undocumented I think, one has to go through the code to actually understand how that works. I recently learned that regexes are supported there.
  
  
  • I didn't know that the extension's settings are using JSON Schema, I don't think this is mentioned anywhere in the docs either.
  
  
• The following nav bar is kind of useless, for ~95% of the page we are always in the "workbench" section, maybe sub sections should be implemented.

• Maybe if there was a button or something for expanding all those collapsible sections the whole page would become more searchable.

[aaronbushnell]

Apologies if this isn’t in scope since it’s not an “extension”, but I’d love a better way to see what part of the Code UI corresponds to a workbench color customization. I like tinkering around with different color changes but often find it difficult to see which element is which.

[octref]

@fabiospampinato I agree with most of what you said. Just to make sure, the one on when clauses is about the when for keybindings, is that correct?

[lannonbr]

@octref So I am wanting documentation on examples for Unit Tests for extensions and it has already been issued on Microsoft/vscode-extension-samples#91 and I personally would be willing to write up an example here on how to do such.

[eamodio]

when for keybindings and menus/commands

[fabiospampinato]

@octref keybindings, commands, views, all of them, the syntax is just undocumented. At first I thought it was just some eval-ed javascript, but it's not.

[qcz]

@octref: It would be great if the limitations of extensibility were documented. For example files larger than a given size are not synced to the extension host, but the extension only sees that window.activeTextEditor is undefined. I found out this the hard way, as my extension, which was created to filter information from larger log files was not working when big files were opened, but I only saw that activeTextEditor is undefined.

The VS Code API docs does not state in which circumstances activeTextEditor may be undefined. Obviously it is undefined when there are no editors open, but as it turns out it is also undefined when the file is not synced to the extension host.

I had to find out this when searching for related issues, and found #3147, which contains some information, however it is not even up to date.

[YurkaninRyan]

I love looking at the vscode extension examples, however I feel like the examples are not commented at all, and it can be hard to follow along with the code.

For example, I'm currently trying to follow along with the multi-step input example. Here is the extension.ts

'use strict';

import { window, commands, ExtensionContext } from 'vscode';
import { showQuickPick, showInputBox } from './basicInput';
import { multiStepInput } from './multiStepInput';
import { quickOpen } from './quickOpen';

export function activate(context: ExtensionContext) {
    context.subscriptions.push(commands.registerCommand('samples.quickInput', async () => {
        const options: { [key: string]: (context: ExtensionContext) => Promise<void> } = {
            showQuickPick,
            showInputBox,
            multiStepInput,
            quickOpen,
        };
        const quickPick = window.createQuickPick();
        quickPick.items = Object.keys(options).map(label => ({ label }));
        quickPick.onDidChangeSelection(selection => {
            if (selection[0]) {
                options[selection[0].label](context)
                    .catch(console.error);
            }
        });
        quickPick.onDidHide(() => quickPick.dispose());
        quickPick.show();
    }));
}

this line alone I have a ton of trouble following

const options: { [key: string]: (context: ExtensionContext) => Promise<void> } = {
  showQuickPick,
  showInputBox,
  multiStepInput,
  quickOpen,
};

Let me tell you the things I do like about the dev documentation experience so far

1. So far, when it comes to explaining types, and what different apis are expecting, the documentation is very well done. I think some things are confusing like getParent in TreeDataProvider, but overall i've been able to manage and enjoy reading them

1. The webview documentation is really, really good. It's done in simple language, it's easy to follow, and shows results along the way. I wish more documentation was like that.

[octref]

@qcz That makes sense. One of my original motivation was to extract scattered information on GitHub into a central place that's searchable and more well-organized.

@YurkaninRyan Thanks for the feedback. We can certainly look into making the sample code easier to understand.

[ghost]

I would really like a glossary of all the terms used by developers to describe the components. When someone wants to create an extension, they need to understand what the editor is capable of and how these capabilities are labeled. Acquiring -- and subsequently retaining -- this information is made increasingly difficult with each additional feature. Extension developers periodically need to append new words to their already large repertoire of definitions without any sort of direct reference. Frequently, I believe, someone will also have an idea for an extension, but their limited vocabulary will prohibit them from progressing to a point where the extension is functional.

Throughout discussions, I've seen these words and others used ambigously or interchangeably:

• widget
• window
• peek
• preview/webview
• panel
• view
• explorer
• sidebar
• quick open
• editor
• menu
• viewlet

Here's a list from https://code.visualstudio.com/docs/extensionAPI/extension-points#_contributesmenus detailing contribution points for menus:

The global Command Palette - commandPalette
The Explorer context menu - explorer/context
The editor context menu - editor/context
The editor title menu bar - editor/title
The editor title context menu - editor/title/context
The debug callstack view context menu - debug/callstack/context
The SCM title menu - scm/title
SCM resource groups menus - scm/resourceGroup/context
SCM resources menus - scm/resource/context
SCM change title menus - scm/change/title
The View title menu - view/title
The View item menu - view/item/context

The above may seem quite intuitive for experienced vscode developers, but what about the perspective of a newbie trying to create his/her first extension?

An aggregation of terminology used throughout the community and their associated meanings would make the extension ecosystem much more friendly. Even better would be the usage of screenshots or other visual objects to enhance the definitions.

[VictorMazilu]

+1

On Sun, Sep 9, 2018, 2:02 AM Nealot [e-mail] wrote:

I would really like a glossary of all the terms used by developers to
describe the components. When someone wants to create an extension, they
need to understand what the editor is capable of and how these capabilities
are labeled. Acquiring -- and subsequently retaining -- this information is
made increasingly difficult with each additional feature. Extension
developers periodically need to append new words to their already large
repertoire of definitions without any sort of direct reference. Frequently,
I believe, someone will also have an idea for an extension, but their
limited vocabulary will prohibit them from progressing to a point where the
extension is functional.

Throughout discussions, I've seen these words and others used ambigously
or interchangeably:

• widget
• window
• peek
• preview/webview
• panel
• view
• explorer
• sidebar
• quick open
• editor
• menu
• viewlet

Here's a list from
https://code.visualstudio.com/docs/extensionAPI/extension-points#_contributesmenus
detailing contribution points for menus:

The global Command Palette - commandPalette
The Explorer context menu - explorer/context
The editor context menu - editor/context
The editor title menu bar - editor/title
The editor title context menu - editor/title/context
The debug callstack view context menu - debug/callstack/context
The SCM title menu - scm/title
SCM resource groups menus - scm/resourceGroup/context
SCM resources menus - scm/resource/context
SCM change title menus - scm/change/title
The View title menu - view/title
The View item menu - view/item/context

The above may seem quite intuitive for experienced vscode developers, but
what about the perspective of a newbie trying to create his/her first
extension?

An aggregation of terminology used throughout the community and their
associated meanings would make the extension ecosystem much more friendly.
Even better would be the usage of screenshots or other visual objects to
enhance the definitions.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/Microsoft/vscode/issues/58226#issuecomment-419678487,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AVPRpc4N6eNvB7JY-r1dh6cWs-ZDltJYks5uZEx4gaJpZM4WfiGo
.

[gkalpak]

I only have limited extension authoring experience, but here are some pain points I ran into:

• Testing - Although the testing story is pretty good (all things considered), there are some easy wins to be had imo:

  • Docs on writing tests with Jasmine (some people like it :wink:). The fix is quite straight forward when you know it, but I had a hard time finding out what it takes to succeed.
  • Docs/samples on unit vs e2e/integration tests (see also https://github.com/Microsoft/vscode-extension-samples/issues/91#issuecomment-419809844).
  • Better support for running tests against multiple versions (see also Microsoft/vscode-extension-vscode#96).

• CI Automation

  • It could have saved me quite some time, if there were better docs on how to automate tasks like releasing and publishing on CI.
  • Here is the setup I ended up with, so that I can trigger publishing a new version with just npm version <patch|minor|major> (plus some git pushing).
    _{(Shout out to VSCoceVim/Vim, where most of this is taken from :heart:)}

#

BTW, I interestingly didn't have a hard time following or finding something in the API docs (as others have mentioned), but that could be because I have only used few APIs.

In any case, the overall experience of authoring and publishing an extension was pretty enjoyable :100:

[octref]

@nealot I feel your pain. That was an issue when I was trying to learn VS Code too. I don't think the issue only applies to extensibility doc though — a clear description & illustration of VS Code UI would help regular users getting onboard with the editor too. I opened https://github.com/Microsoft/vscode-docs/issues/1842.

@gkalpak

unit vs e2e test

When I was writing the docs for Language Server I made this distinction: https://code.visualstudio.com/docs/extensions/example-language-server#_testing-the-language-server, but I guess in the general Testing page section could have some doc for that too.

CI

Did you have a look this page? https://code.visualstudio.com/docs/extensions/testing-extensions

[eamodio]

Another big one is documenting menu/command callbacks -- Each context a menu/command is executed from (https://code.visualstudio.com/docs/extensionAPI/extension-points#_contributesmenus) returns a different set of arguments. For some extra context: https://github.com/Microsoft/vscode/issues/25716 and https://github.com/Microsoft/vscode/issues/34048.

I honestly find dealing with commands the most challenging part of the vscode api.

[gkalpak]

When I was writing the docs for Language Server I made this distinction: https://code.visualstudio.com/docs/extensions/example-language-server#_testing-the-language-server, but I guess in the general Testing page section could have some doc for that too.

@octref 👍

Did you have a look this page? https://code.visualstudio.com/docs/extensions/testing-extensions

Yes :grin:
It's a good start, but it could be enhanced. Basically, (as mentioned above) I was looking for a recipe to get me there (or at least some more hints), because I think this is something that makes sense for every extension that uses CI anyway.
_{(Disclaimer: I might be biased towards over-automating 😛)}

[octref]

@eamodio From what I read in that issue, if you are using the same command for multiple contexts you should prepare for different arguments. You can always register different commands for different contexts, can't you?
Although I agree with the point that it's unclear what are the arguments being passed in to the command for each context. This can be addressed with better docs.

[KamasamaK]

Complex Commands should provide clearly formatted, linked types for the parameters and returns as in the "vscode namespace API" doc.

[octref]

@KamasamaK I agree. Many people feel the name "complex command" is confusing too.

[eamodio]

@octref yeah, I could have different commands for each context (and I might start doing that). But I avoided that because that causes SO much duplication in the package.json. For something like GitLens which has lots of commands, it now multiplies them by the number of contexts (which is many and growing). And it requires that I keep them in sync (typo's, renames, etc). And it can be confusing to a user, because now which command do they bind a keyboard shortcut to because there are now 5 versions of many commands.

It gets nuts fast once you move past a small number of commands.

EDIT: Just to dive in a tad more on the keyboard bindings thing -- since a user can assign a binding for any command -- that command can get executed from contexts it wasn't expecting depending on how the user executes that command -- which adds a significant challenge even when trying to use a specific command for each context.

[octref]

@YurkaninRyan

Looking back at the code, was it because the code itself includes many new JS/TS features that it's hard to understand? Because I don't think the code itself is complex — it merely assigns 4 functions as the value of an option, later passed to

• Object Literal Shorthand
• Promise
• TS's type for index key: https://stackoverflow.com/questions/13315131/enforcing-the-type-of-the-indexed-members-of-a-typescript-object

@eamodio That might be a result of the complexity of GitLens's features. You can try opening new issues to persuade @jrieken. One downside of adding a context object to each command's signature might be that it adds unnecessary arguments to commands for single contexts.

[YurkaninRyan]

@octref I actually pulled it down and fiddled with it and eventually figured it out!

I was going there to try and understand how to create the multi step input. I thought the whole repo was just doing that usecase, but in actuality, it was a few different examples that could be selected from a dropdown, and one of those examples was the multi step input.

I had problems figuring out:

1. What was the entry point that I should be paying attention to.
2. Why am I doing anything like creating a helper multistep input class.
3. What are extra features that arent involved in the "hello world" of creating a multi step input. For example that example implements a "shouldResume" flag, which I think complicates the code a lot. There's a lot of different apis there to digest all at once.

If there was any commenting or direction pointing it would of helped a lot. I had similar struggles in most of the examples. I wasn't sure what to look at, or why I was looking at it.

[heatherlp]

As you've already come across, the complex commands page needs improvement.

• not all commands listed on that page explain the return value
• Are the commands listed on that page a full list of those supported with executeCommand? I've seen setContext used, and that's not listed on that page.

My biggest pain point in extension development has been surrounding the fact that on opening a folder in the current window, the current extension host process is shutdown, and so you have to activate the extension on the new window/folder in order to access it (i.e. to call createTerminal). I'd appreciate some further documentation surrounding how vscode handles folders, workspaces etc, for extensions that want to create, open and close folders.

[visualzoran]

I agree with previous posts about "where" for menus/commands. It was the biggest problem for me when I was creating some extensions in the past.
But I would also like to see more documentation about exposing public API from extensions. I've been creating multi-file template engine extension that allows to visually select templates and allows to run additional wizards, specific to selected template. I only wanted to implement core engine and UI in the main extension and then allow dependant extensions to use API to register new templates and wizards. The only information I was able to find was a short note in vscode-api document that "activate" method can return public API. I've managed to do what I wanted, but it would be nice to have some sort of example and suggested list of tasks that should be done by a developer creating extension of that type. Something like:

1. That's how you can return API from your extension - and very simple example here
2. You have to publish your public APIs to other developers. It might be a good idea to do it by creating and publishing npm module - and maybe an example or link to sample module with API exposed in step above?
   Maybe we just need to add another example to the list of your sample extensions?

[octref]

@visualzoran Thanks — extension can expose its own API is something that even I didn't know it existed. I'll include it as a topic in the new extensibility doc.

[KamasamaK]

I too just recently learned about extensions exposing public APIs by seeing the git extension do it, and would be interested in learning more.

[octref]

Thanks a lot for all your valuable feedback! We have created an internal plan to address most of the issues. In the next one or two iterations, we'll do the minimal work possible to publish the new extension authoring doc. After publishing the new docs, we'll write new topics, edit old ones and make improvements to pages such as the API reference.

[Almenon]

Generally speaking the more documentation, the better. The webview documentation was great and it would be nice to see stuff like that for other parts of the API. For example, there are no guides on how to add telemetry to your extension. so I wrote my own: adding telemetry with azure and setting up email alerts. Because of the outstanding bug with the innacurate download counts telemetry is important to see how many users you have.

@lannonbr also wrote some good guides on decorations and unit testing.

[KamasamaK]

One other thing I forgot to mention and haven't seen anyone else mention is that the API and complex command references are lacking an indication of what version the item was added at.

[busticated]

minor but helpful things:

• make the property / method names easily copy+paste-able (ex. createOutputChannel here)
• in each property / method section, include the full parent reference so i don't need to scroll around to find it - e.g. window.createOutputChannel()

🙏

[busticated]

another one: the docs for the configuration contribution point make no mention of the scope field - yet we are warned about setting it / not setting it under certain circumstances. what does scope do?

docs:
https://code.visualstudio.com/docs/extensionAPI/extension-points#_contributesconfiguration

example:
https://github.com/Microsoft/vscode-extension-samples/blob/master/configuration-sample/package.json#L42

warning:
https://github.com/Microsoft/vscode/issues/36623
https://github.com/Microsoft/vscode/wiki/Extension-Authoring:-Adopting-Multi-Root-Workspace-APIs#run-time-diagnostics

@octref is there a better place to log these types of things since this issue is now closed?

[octref]

@busticated Can you post a new issue under https://github.com/microsoft/vscode-docs/issues? I'll tackle it there.

The two issues you listed above for the API doc — we have a huge backlog for that page. We'll do it from scratch and I've taken notes, so no need for new issues on those two.

[octref]

Hey all, as some of you might have noticed, we had a multi month effort to refresh our Extension API doc. The work is near complete and will be published soon. A preview is available at https://vscode-ext-docs.azurewebsites.net/api. If you have any feedback, feel free to open an issue at https://github.com/microsoft/vscode-docs and mention me.

The update focused on making structure changes that make the doc easy to navigate and find information from. We also added new topics such as Extension API Overview, Extension Capability Overview to help you better utilize the vast extensibility system, and new guides/samples such as Tree View / Color Theme / Textmate Grammar.

From the writers & contributors' perspective, this update makes it easier to add new topics and make changes. This should lay down a good foundation for us to address the extensibility issues in vscode-docs repo. We'll continue to refresh the Extension API doc, and we welcome your contribution too 😉.