Make `langword` a first-class citizen attribute of the `<see />` tag

[Eagle3386]

Summary

Please, I'm begging you people, stop enforcing tedious edits of <see cref=""/> just to get <see langword"" /> for us XML-Doc-savvy developers.

Background and Motivation

Right now, the VS text editor never stops for selection of either cref or langword as attribute, but goes straight for <see cref="|"/> (Note: | marks cursor's spot).

But it gets even worse as langword is still not offered after removing everything right of <see - triggering IntelliSense at <see| will only offer <see cref="… & <seealso cref="….

That leaves us forced to:

1. Add a single whitespace between " & / to make it XML-compliant.
2. Move the cursor left of = in order to delete cref & then insert langword instead.
3. Continue with our docs by inserting the language word, e.g., true.

Every. Single. Time. Really?

Proposed Feature

Part I:

1. Make IntelliSense stop at <see | />, prompting to select either cref or langword.
2. After either selection, at least in case of langword, prompt to select the attribute's value (<see langword="|" />).
3. After completion, move cursor past the closing angle bracket.

Part II (might be done in a separate issue - tell me & I happily create it):

1. Make the <see /> tag XML-compliant by inserting a whitespace before the slash (/).
2. Extend this to any self-closing / standalone XML Doc tag, i.e., <include />, <inheritdoc /> & <seealso />, too.

Alternative Designs

Manual edits. Just like above: Every. Single. Time.

[CyrusNajmabadi]

You don't need to type <see langword="the_keyword". You can just write the_keyword, and the lightbulb will automatically give you the option to replace it with <see langword="..."/>.

[Eagle3386]

@CyrusNajmabadi While that's true, it's nothing but a workaround, because it breaks fluent docs typing & neither solves anything of Part I above, i.e., langword is still not offered if modifying an existing <see /> tag, nor does it allow for the optional whitespace prior to />.

[CyrusNajmabadi]

While that's true, it's nothing but a workaround

Workarounds are an acceptable thing for us to consider :)

Moving this to the backlog, will put in an appropriate area we're going to make where we're considering what sort of improvements we want to do in xml doc comments.

[Eagle3386]

Workarounds are an acceptable thing for us to consider :)

And I thought describing it like that would prevent exactly this comment. 🙈😅 Please don't. We need that feature, especially given how small the required amount of work should be - I really put some thoughts in here, please acknowledge it at least a little bit! 😉

Moving this to the backlog, will put in an appropriate area we're going to make where we're considering what sort of improvements we want to do in xml doc comments.

As long as it's not "file 13" (translator's suggestion for "Ablage P", which literally translated means "tray P" - with "P" short for "Papierkorb" & called "Recycle Bin" in any Windows since '95 or so), I'm fine with that! 🥳

[CyrusNajmabadi]

especially given how small the required amount of work should be -

This risks breaking people's muscle memory. We cannot make those changes to behavior that people have been using for 25 years casually.

please acknowledge it at least a little bit!

I def have. That's why this will be in the area where we are tracking potential investment areas to improve here.

[Eagle3386]

This risks breaking people's muscle memory. We cannot make those changes to behavior that people have been using for 25 years casually.

Let's face it: those using XML Doc to such an extend are pretty hardcore anyway (we're talking about 4 (!) tags only) & those people probably adapt quickly, given the time saving improvement - besides, Visual Studio did worse things in the past & got away with it easily. 😉🥳

[CyrusNajmabadi]

& those people probably adapt quickly

This is very much not the case. Breaking muscle memory often impacts a lot of people and causes a lot of upset typers.

besides, Visual Studio did worse things

Roslyn has tried very hard to not do this. And when we have, we have received a lot of negative fallout and have often had to revert. We do not casually break muscle memory scenarios. Especially when we've had behavior for 25 years, there is a workaround, and there is only a single report from a single customer in all that time.

We have millions of customers. We have to balance the needs of that enormous group versus the desires of individuals who would like the product tweaked to better suit how they want ot use it.

[Eagle3386]

You don't need to type <see langword="the_keyword". You can just write the_keyword, and the lightbulb will automatically give you the option to replace it with <see langword="..."/>.

This won't work for init, true, etc., though. 😞

& those people probably adapt quickly

This is very much not the case. Breaking muscle memory often impacts a lot of people and causes a lot of upset typers.

Then your mileage greatly varies from mine - yes, there's some "Boo, that used to be X/Y/Z". But if the advantage was made very clear & outweighed the "break in muscle memory", adoption rate reached 100% after 2 weeks at a max. 😅

Roslyn has tried very hard to not do this. And when we have, we have received a lot of negative fallout and have often had to revert. We do not casually break muscle memory scenarios. Especially when we've had behavior for 25 years, there is a workaround, and there is only a single report from a single customer in all that time.

Well, that's not fully correct - there are at least 3, see the ❤️ of my OP. 😉

And the workaround, as proven above, isn't that much useful as it seems it's pretty much limited to type-keywords - compared to way more language words like async, await, false, init, true, etc.

We have millions of customers. We have to balance the needs of that enormous group versus the desires of individuals who would like the product tweaked to better suit how they want ot use it.

Now, that's not fair. I don't ask for a "tweak". In fact, I'm asking to just apply the same logic that's used throughout the IDE's text editor for other snippets & stuff like that to rather the full extend than only half of it.

[CyrusNajmabadi]

This won't work for init, true, etc., though

Then we can fix that. If you want to submit a pr fixing missing keywords there, we would take that.

Then your mileage greatly varies from mine

Correct. We have decades of experience here, and we know just how upset people get when you break muscle memory.

And the workaround, as proven above, isn't that much useful

We can address that separately. If we're missing keywords, we can add them.

I don't ask for a "tweak". In fact, I'm asking to just apply the same logic that's used throughout the IDE's text editor for other snippets & stuff like that

Yes. That's a tweak. I get what you're asking for. I'm telling you it's something we will evaluate. I'm also telling you the things we have to take into consideration when doing that evaluation. :-)

[Eagle3386]

Then we can fix that. If you want to submit a pr fixing missing keywords there, we would take that.

Sure, do you mind pointing me in the right direction as to where the necessary file(s) are?

Correct. We have decades of experience here, and we know just how upset people get when you break muscle memory.

Honestly, I really appreciate talking to you, Cyrus! It's been a productive conversation/suggestion, from which I take your insights for my own developer life - thanks!. And that's even for when we agree to disagree - awesome! Just keep being like you are, Cyrus. Wow, that almost sounds like a love confession.. 🙈😅

We can address that separately. If we're missing keywords, we can add them.

I'd love to get this going. The more you could help me on that, the sooner we all got the improvement(s). 😎

Yes. That's a tweak. I get what you're asking for. I'm telling you it's something we will evaluate. I'm also telling you the things we have to take into consideration when doing that evaluation. :-)

Much appreciated! Very much! ❤️

[CyrusNajmabadi]

Currently traveling. I would look for some tests that validate the langword refactoring and then see what class they are testing. The fix would be somewhere in that code refactoring provider.

If you can't find it, lmk, and I'll add the info when I'm settled someplace.