[documentation] add information regarding all available commands and their descriptions

[marcdumais-work]

Description

The goal is to provide users with the ability to view all available registered commands present in the framework, alongside helpful descriptions of their functionality. Such a reference can then be easily added as a menu entry under the Help menu for users to reference.

[akosyakov]

Do you mean to have a widget which inspect CommandRegistry and show information about all registered commands by the current moment?

[vince-fugnitto]

Do you mean to have a widget which inspect CommandRegistry and show information about all registered commands by the current moment?

I like the idea of having a widget describing all available commands and their descriptions if available. The original issue argued that we should provide documentation on commands (their description, their context) for end-users and then reference them in the Help menu. AFAIK, VS Code does not provide such documentation since commands are self-explanatory or they argue to use the keybindings widget to see available commands.

I'm not sure what the best approach would be in a case like this, I'm worried about the maintainability of such a document.

[akosyakov]

They have some docs to be fair: https://code.visualstudio.com/api/references/commands

The problem with commands that it is API, if we document something it should be stable, otherwise such documentation will rot fast. But i see the same issue with the widget, if it would be very easy to look up commands then users start using it in different places (like one can use them in webviews or markdown files, like [open](command:do.someting?args)). We will break them if a command disappears later. We could have metadata to mark that command is stable, it would mean that it cannot be removed before next major or its signature should be changed in the backward compatible way.

[vince-fugnitto]

They have some docs to be fair: https://code.visualstudio.com/api/references/commands

The problem with commands that it is API, if we document something it should be stable, otherwise such documentation will rot fast.

I completely agree :+1:

[chrisjj]

They have some docs to be fair: https://code.visualstudio.com/api/references/commands

"This document lists a subset of Visual Studio Code commands that you might use with vscode.commands.executeCommand API."

That's not a list of user commands.

The problem with commands that it is API, if we document something it should be stable, otherwise such documentation will rot fast.

This documentation i.e. Command Help won't rot at all if it is gathered at the appropriate time i.e. after any addition, deletion or modification of the entry of any command.

But i see the same issue with the widget, if it would be very easy to look up commands then users start using it in different places (like one can use them in webviews or markdown files, like [open](command:do.someting?args)). We will break them if a command disappears later.

That's not a problem of documentation. It is a problem of API instability.

[chrisjj]

AFAIK, VS Code does not provide such documentation

VS Code seems rather a low bar. Theia aims to improve on VS Code, right?

[chrisjj]

I'm not sure what the best approach would be in a case like this,

The widget sounds good to me.

I'm worried about the maintainability of such a document.

I don't understand this. The widget would make the document automatically as required. There's no manual document maintenance.