Encode SymbolKind and SymbolTag as strings

[astoff]

I would like to propose changing the SymbolKind and SymbolTag enum values to strings, so SymbolKind.Function = "function" instead of 3, and so on.

Most languages probably have one or two features that don't quite fit in the existing collection of SymbolKinds (e.g., patterns in Haskell, so this change would allow servers to better handle these edge cases.

On the client side, the spec already says that clients should “handle values outside [the SymbolKind] set gracefully and falls back to a default value when unknown”. Therefore, servers are already allowed to send strings as SymbolKind. I'm simply suggesting to encourage this practice when necessary, and also to make the existing API more consistent with it.

Sending strings as the SymbolKind in edge cases is a reasonable thing to do because, while there isn't anything particularly graceful the client could do with an unknown value of 99, there is definitely something useful it could do with a value of "pattern", or "pragma" (e.g., show that word in a menu).

This is not to say that there shouldn't be an official set of values for SymbolKind, and of course most servers will stick to the official set for better compatibility. Issue #344 remains relevant, as it would be task of the LSP specification to collect the most useful SymbolKinds and make them official.

My interest in this, concretely, concerns the TeX markup languages. In this case, the relevant SymbolKinds would be things like

• chapter/section
• environment
• cross-reference
• citation

and there's nothing reasonable to choose from, even in the way of analogy, from the current options. Now, mine is a very particular case, and I have no hope of convincing you to spec out those things; I myself would be against it if I was in charge of LSP. So I'd rather send the above SymbolKind values as strings to the editor, and let it do its best with that. Surely the editor can create a nice document outline without knowing what the semantics of "chapter" are.

For SymbolTags, it's probably even more desirable to allow nonstandard values to address the idiosyncrasies of particular languages.

[dbaeumer]

This is potentially breaking. To keep it backwards compatible we would need to add a client capability to signal that.

Showing string enum values in the UI is problematic when it comes to i18n.

[astoff]

This is potentially breaking. To keep it backwards compatible we would need to add a client capability to signal that.

The specification already says that unrecognized values should be handled gracefully:

                         * The symbol kind values the client supports. When this
			 * property exists the client also guarantees that it will
			 * handle values outside its set gracefully and falls back
			 * to a default value when unknown.

Showing string enum values in the UI is problematic when it comes to i18n.

It still seems easier (or at most equally hard) to translate "function" -> "função" than 12 -> "função".

[mitonize]

@astoff
I totally agree with you.

@dbaeumer
Who should be able to define language specific SymbolTags?

[dbaeumer]

We usually collect them in issues like: #344

[astoff]

Has any of the suggestion made in #344 ever made it to the spec? The first ideas mentioned there, pragma and macro, have not. Same for the section kind that I was looking for — it was first mentioned in January, 2019.

[kraigher]

I am working on a language server for the VHDL language. VHDL is a hardware description language that has a lot of elements that do not fit into the pre-defined symbol kinds.

I think it is a futile effort to try to globally define all kind of symbols in the LSP-spec, there are just so many types of languages in the world. For example this issue mentions LaTeX stuff like chapter and cross-reference. For VHDL there is architecture, entity, configuration, context and many more. The set of symbol kinds is probably large and it is not feasible for all clients to know about this global list and do anything useful with it. The current architecture pushes non-mainstream languages into poor UX or to having special clients tailored to the server which defeats the purpose of the LSP.

Thus I really like this proposal to support server-defined symbol kinds via a string keyword. I think it is a much better architecture. The client can then show the symbol kind keyword as a prefix of the symbol. It is probably good to keep a short list "meta kinds" as part of the LSP protocol which would map to icons in the clients. The current list of hardcoded symbol kinds could probably be kept as such "meta kinds". The list of "meta kinds" would be global and smaller. The server defined symbols would inherit from an existing symbol kind but add their own string keyword.

Having symbol kinds as strings would have improved the UX of my VHDL language server since I could differentiate between entity, component, 'architectureand other constructs in the language. This would also allow supporting a well definedworkspace/symbolfiltering based onSymbolKind` as well related to #1674 and #1382.

@dbaeumer I do not think i18n is relevant objection to having named symbol kinds. Names or keywords denoting a language construct is probably expect knowledge for someone working in a programming language and has to be typed in english in the file by the user as a keyword anyway in many cases. Also the LSP The server will produce diagnostics and other text messages in english anyway. The protocol supports sending a locale from the client to the server that I assume would cause the server to change the language of its diagnostics. This could also be used to translate the named SymbolKinds as well if the server deems it useful.

Proposal

Add a new server defined NamedSymbolKind:

interface NamedSymbolKind {
   // The base kind of the symbol, used to select an icon in clients 
   kind: SymbolKind,
   // Keyword to show as a prefix of the symbol
   name: string,
}


// Published by the server. 
// The index is used to compactly encode the symbol in future messages.
// Several named symbols may use the same SymolKind
type NamedSymbolKinds = NamedSymbolKind[];

The idea is that the kind serves as a meta kind to select an icon. Several NamedSymbols can use the same symbol kind but with different names.

In VHDL there are several things which could be considered a MODULE and in LaTeX several things might be a NAMESPACE. Those can all use the same icon but be disambiguation by the name prefix in the UI.

[pidgeon777]

@kraigher To me, this seems to be a great idea. Hopefully, Microsoft Team will consider your proposal 👍.

[dbaeumer]

Instead of adding an additional type I would rather do something comparable to semantic tokens. That would be:

• a client capability so that client's can opt into it. By default that would be false. But servers need to deal with the fact that clients might never implement it.
• If clients opt into this server can send in the initial response that additional kinds and tags they want to use and which index they use to refer to it.

[kraigher]

@dbaeumer I think the key attributes of a solution is:

1. There needs to be a small set of "meta kinds" that are defined by the protocol essentially mapping to generic icons that represent concepts such as "Type", "Object", "Namespace" similar as today.
2. The server can "instantiate" the meta kinds with a name denoting a language construct or keyword. Clients would render "icon + keyword" as prefix of the symbol. The important aspect is that one meta kind can be instantiated several times with different names.

If these two key attributes are fulfilled the clients are happy since they can have a small global list of icons for concepts and servers are happy since they can create a specific set of tags that match 1:1 with the constructs of the programming language at hand.