add diagnostic dynamic long description

[RobbyCBennett]

#1461

[RobbyCBennett]

@microsoft-github-policy-service agree company="Scientific Toolworks, Inc."

[dbaeumer]

@RobbyCBennett tahnks for the PR. Changing the spec is the easy part :-). To contribute additional functionality to the spec a reference implementation is needed as well. See https://github.com/microsoft/language-server-protocol/blob/main/contributing.md

I will keep the PR open for a while but without a reference implementation I will not be able to merge the PR.

[jwortmann]

Isn't this a breaking change?

Currently, the href field is mandatory. With this PR, it would become optional. So any client which unconditionally tries to read href might crash if the field doesn't exist.

[RobbyCBennett]

To contribute additional functionality to the spec a reference implementation is needed as well.

Thank you. I was just looking to get some feedback before the reference implementation is made.

Isn't this a breaking change?

Yes, I will change it to accommodate for language clients that will crash after assuming the href field is defined.

Perhaps instead, it could be simplified to be part of Diagnostic, as a new field longMessage that could be just below message. I think that this would be more clear and it also wouldn't break language clients.

1348fc7

[rchl]

The naming of the property can suggest that it's an alternative version of message. Not sure if the intention would be that clients show both or choose one.

If the intention is to show both then maybe this should be called description...

[RobbyCBennett]

Calling it description would be too similar to the property called codeDescription, which is a general/static description of the diagnostic.

In contrast, I thought about calling it longMessage because it is similar to message but provides more detail. Perhaps something like messageDetails would be more appropriate. I think that would infer that message is still important.

[RobbyCBennett]

I didn't follow https://github.com/microsoft/language-server-protocol/blob/main/contributing.md because it seems to be intended for adding new types and methods.

Reference implementation:

Step 1: (this PR)

• Add messageDetails field to Diagnostic

Step 2: PR in VSCode repo:

• Add messageDetails field to Diagnostic (this is a different Diagnostic interface, defined in src/vscode-dts/index.d.ts)

Step 3

• Update the projects that get their 2 Diagnostic types from these 2 repos (like the npm module @types/vscode), which should prepare for step 4.

Step 4 (PR in VSCode Language Server Node repo):

• Change asDiagnostic function in createConverter and add asMessageDetails function (in client/src/common/codeConverter.ts)
• Change asDiagnostic function in createConverter and add asMessageDetails function (in client/src/common/protocolConverter.ts)