Roslyn: Add a <see langword option in the completion window

[davkean]

I often type <see langword="true"/>, <see langword="false"/>, <see langword="abstract"/>, etc like below. It would be great to be offered to add an add <see langword=""/> like there is with <see cref=""/>.

C# /// <summary> /// Returns a value indicating whether the current project has the specified capability /// </summary> /// <exception cref="ArgumentNullException"> /// <paramref name="capability"/> is <see langword="null"/>. /// </exception> bool Contains(string capability);

[miloush]

The only problem I see with that is that see langword does not seem to be part of the C# specification...

[Pilchie]

@miloush we crossed that bridge when we started adding support to them to quick info. The XML doc tag section of the spec explicitly says that the schema can be extended, and langword is a quite common extension.

[lorcanmooney]

What sort of completion-list entries would you expect for this? Something like the following?

[Pilchie]

I think that could work. Alternatively, we could make it so that see<space> only completed see space, and then show a follow-up completion list with cref and langword. Thoughts @DustinCampbell @kuhlenh @rchande?

[DustinCampbell]

That's what I'd prefer. Much like VB's completion list works for multi-word completions (e.g. End Class).

[lorcanmooney]

So, step-by-step, the user commits the see item...

<see$$/>

...presses SPACE...

``` ┌┐└┘─│

│ cref │
│ langword │
└──────────┘

...then commits `langword`...

```

...and is presented with the suggestion list from #11490?

[lorcanmooney]

The VB implementation can already suggest attributes. If it's acceptable, I could refactor it to work for C#, and make it trigger on <space>. That would provide the same behaviour for other tags/attributes.

[Pilchie]

Tagging @CyrusNajmabadi and @rchande too, but yes, I think that's the right approach.

[lorcanmooney]

I've got this all but done. As requested, I've change the commit behaviour for <space> to commit only the tag name, and trigger the completion list. Values are now eagerly suggested for a handful of well-known tag/attribute combinations in both C# and VB:

I've left the other commit modes as they are, so <tab> will still commit <see cref="$$"/>.

I'll open a PR once #12292 is merged.

[lorcanmooney]

I've submitted #13671 with the changes for this. Please try it out at your leisure and let me know if any changes are needed.

[sharwell]

I very much prefer the behavior implemented in the SHFB extension¹. The completion list looks like this:

The primary advantages of this are the following:

1. The behavior of <see is unchanged, so it doesn't cause a problem for people used to typing <see+Space and assuming it'll place the caret inside a cref attribute.
2. Code completion works by simply hitting Ctrl+Space on the word static, true, virtual, etc., expanding them into their "full" forms with a <see langword="..."/>.

¹ I am biased because I implemented this feature, but I would argue that doesn't necessarily make it bad.

[CyrusNajmabadi]

I like sam's suggestion that keywords just be in the list, and that they expand to the <see langword construct. IN that way, they're just basically contextual snippets that provide a convenient shorthand.

However, the overall design on how <see should work is consistent with our design principles. Specifically, if someone wants to type <see<space>langword then we should not be messing with them, generating really bad code.

[sharwell]

@CyrusNajmabadi We're in agreement on the design principle. If the feature were not already in place, I would advocate for not completing the cref attribute, especially considering its interference with the related tag <see href="[Some URI]"/>.

However, automatic completion of the cref attribute was added for the Visual Studio 2010 release, and finally updated in Visual Studio 2015 to its current behavior (2010-2013 inserted a space inside the quotes which users had to delete).

• Users who write documentation using the see and/or seealso elements are going to notice this difference.
• The subset of these users who do not use the langword and/or href forms currently are not going to be happy.

[DustinCampbell]

However, automatic completion of the cref attribute was added for the Visual Studio 2010 release.

@Pilchie: Is that right? Did we fiddle with that behavior back then? Was it because we didn't have XML doc comment attribute support in completion at the time?

[sharwell]

@DustinCampbell I tested them all! 😄

[DustinCampbell]

:smile:

I have a vague recollection of the change, though I was actually the VB IDE PM for VS 2010. I did shepherd through the completion list filtering changes in VS 2010 for both C# and VB though, so I was pretty close to IntelliSense at the time. I just didn't remember this change.

You'll find the @Pilchie just remembers all of this stuff. He doesn't have to test old versions. :smile:

[Pilchie]

I don't remember making deliberate changes here for VS2010 - the last change I remember making to doc-comment completion pre-Roslyn was when I re-wrote in early 2004...

[DustinCampbell]

I though you rewrote the XML doc comment generation, not completion.

I have a vague memory of a change here in VS 2010. (BTW, this discussion is more about curiosity now. @Pilchie and I are old men who need to double-check our memory recall occasionally).

[jnm2]

null, Ctrl+Space
Ctrl+Space, n, Space

Both of these just totally made my day, but they are not at all discoverable. During organic usage, null was never offered. I had to start by coming here to ask for <see langword=", and searching existing issues, and reading through a bunch of comments. I didn't know Ctrl+Space was a thing.