Extensions Documentation: Extension Capabilities

[bamurtaugh]

Common Capabilities

When I was trying to figure out a mechanism for maintaining state across launches of my extension, I wasn't sure what to use. I eventually found https://code.visualstudio.com/api/extension-capabilities/common-capabilities, and realized Data Storage would be really helpful to maintain state.

However, I had trouble finding an example of how to use it. I found a Stack Overflow question that posed essentially the same question and was also hoping to see an example of the usage. I ended up solving my issue through trial/error and locating an external sample app.

Common Capabilities proposed change/question:

• Since there are quite a few Common Capabilities, it may not make sense to just integrate a sample for this specific category. However, I also thought this specific capability may be impactful enough to warrant introducing a small piece of sample code or additional explanation. Any ideas or feedback other folks have here would be great.

Theming

When I was reviewing https://code.visualstudio.com/api/extension-capabilities/theming, I noticed "Product Icon Theme" was the only theme without a screenshot. As themes are especially visual, I found the screenshots for the other two categories to be very helpful.

Theming proposed change/question:

• Is there a reason "Product Icon Theme" doesn't have a screenshot? Could one be added? I believe it would help clarify how it is similar/different to the other two themes.

[ornelladotcom]

re: the Theming part of the issue Product Icon Theme is currently in preview and there's a note in the guide that says: Important: Product icon themes are still in preview. The product icon theme format might still change. Until then, an extension defining a product icon theme needs to set enableProposedApi. Running a extension is limited to extension development in Insider release. Also, you cannot publish extensions such an extension to the Marketplace. We will definitely want to update this page with a screenshot, but let's maybe wait until the format is finalized so we can get the screenshot right.

[bamurtaugh]

Thanks for the feedback @ornellaalt, that's really helpful. I agree it would make sense to wait until the format is finalized before introducing a screenshot.

@eamodio Regarding the first part of the issue with Common Capabilities, it'd be great to get your thoughts here. We were thinking of not making any changes for now and instead just keeping this topic in mind in case other folks asked in the future (since I did find that other Stack Overflow issue posing the same question and asking for an example).

[eamodio]

This is probably out of scope for what you are presenting here, but the "flow" of the Common Capabilities page feels off to me.

For example: Instead of

Command
Command is central to how VS Code works. You open the Command Palette to execute commands, bind custom keybindings to commands, and right-click to invoke commands in Context Menus.

An extension could:

Use something like

Commands
Commands are an integral part of VS Code. Commands can be executed from the [Command Palette](link-here), bound to custom keybindings, and invoked from right-click [Context Menus](link-here?).

An extension can:

Also Keybinding -> Keybindings, Context Menu -> Context Menus, Data Storage -> Storing Data, etc

IMO, the Context Menu section should also mention the tie-in to the Commands section, because the commands contribution is the "definition" and the menus contribution is the "placement". I feel like we should make that more clear.

Data Storage feels a little strange as the first two items are actually built-in data storage mechanisms, while the last two are more roll-your-own options. I feel like those should be separate somehow. Also having another page or something with more details and/or example scenario(s) about workspaceState and globalState imo would be very helpful to new users.

While we have a Quick Pick section, I think we should explain in a sentence what the quick pick is, and we imo are missing an Input or Quick Input section for the inputbox apis.

We also don't mention views here -- which is maybe OK since this isn't exhaustive, but they are a major extensibility point, that feels like a gap.

It would also be great to link each section to a sample (if there is one).

[bamurtaugh]

Thank you for the feedback @eamodio! I like your suggestions for the flow- making the headers and explanations plural and a bit more natural makes more sense. That's also a good point to tie in Commands more into Context Menu.

I also think that having details or example scenarios with workspaceState and globalState would be very helpful to new users- that was the main reason I had opened this issue. I just hadn't found further details or example scenarios to link to currently. Perhaps introducing these down the road as new samples are created and we can link to them would make sense.

Those are also good points about adding additional info about Quick Pick and views.

What are your thoughts @ornellaalt? I think we could at least make the flow changes Eric suggested (i.e. changing terms/titles to plurals) as that would help with readability and not require introducing or creating new examples, if you also think it would make sense.

[gregvanl]

Closing old issue. Good comments and suggestions here but no current plans to update the current extensibility documentation