Update F1 keywords for tokens with multiple uses

[BillWagner]

A number of C# tokens have different semantics depending on where they appear in the syntax tree. Historically, these tokens have gone to a page for the token, and the reader needs to select a link to the page with the correct content. We can do better. Here are the tokens that have multiple uses, the current page, and the list of uses for that token:

• class: goes to class declaration page.
  • declare a class
  • specify the class constraint on a generic type parameter.
• default: goes to a landing page to select the use.
  • default label of a switch statement
  • default operator or default literal.
• enum: destination describes declaring an enum.
  • declare an enum type
  • generic constraint where the base type must be an enum (derived from System.Enum)
• in: destination is a landing page for user to decide.
  • specify contravariance in a generic type parameter
  • parameter or argument modifier, meaning pass by read-only reference
  • in as part of a foreach statement.
  • part of a from clause in a LINQ query expression
  • part of a join clause in a LINQ query expression
• internal: destination is the page for internal access.
  • internal access
  • part of protected internal access
• new: goes to the new expression page, with a link to the method modifier.
  • new expressions
  • new method declaration modifier
  • new constraint on generic type parameter
• out: landing page for the user to specify
  • specify covariance on a generic type parameter
  • parameter or argument modifier meaning pass by reference, set by called method
• private: goes to private access modifier
  • private access
  • part of private protected access modifier
• protected: goes to the protected access modifier
  • protected access
  • part of protected internal access
  • part of private protected access
• ref: goes to the page for ref parameter / argument modifier, ref return and ref local. Page has link to ref struct usage.
  • ref parameter / argument modifier
  • ref return value
  • ref local variable.
  • ref struct declaration
• static page goes to static modifier on class, field, method, local function, or lambda declaration
  • static modifier.
  • part of the using static directive.
• struct: page goes to struct declarations (which includes ref struct and readonly struct.
  • declare a struct
  • specify the struct constraint on a generic type parameter.
• this page is for this referring to the current instance of a type
  • refer to the current instance of a type
  • parameter modifier for first argument of an extension method
• using goes to a landing page for different uses.
  • using directive
  • using static directive
  • using statement
• partial: already has separate pages for type and method
  • partial type
  • partial method
• where: already has separate pages for both usages
  • where LINQ query expression
  • where generic constraint

The readonly modifier can be used in different contexts, but the meaning is generally the same. It makes sense to keep them on one page.

The first step would be to add F1 token meta data for all the correct destination pages. Then, the Visual Studio IDE could update its F1 source to send readers to the updated pages.

/cc @CyrusNajmabadi @davidwengier

[Youssef1313]

@BillWagner, What about updating Roslyn to give different F1 keywords when the keyword can have multiple meanings? I recently did this with ! (null forgiving vs logical not). Docs PR - Roslyn PR.

[davidwengier]

@Youssef1313 Yes, that was the intention with this issue. The docs pages need to be checked and updated with unique f1_keywords, and then the appropriate Roslyn-side changes made. Bill logged this issue as a checklist of items to work through, essentially.

[Youssef1313]

@davidwengier That's good. I thought the intention was docs-only changes (i.e. the linked page should explain the different semantics about the keyword or contain links that explain them). Thanks for clarifying my misunderstanding.

Let me know if I can help with roslyn-side fixes on this.

[davidwengier]

Let me know if I can help with roslyn-side fixes on this.

I don't think there is much point logging help wanted issues for all of these on the Roslyn side, but if you wanted to contribute the PRs like you did with ! as you mentioned, I'm sure that would be welcomed from docs and roslyn equally.

I've logged dotnet/roslyn#48392 on our side so we at least don't forget :)

[Youssef1313]

• private: goes to private access modifier

  • private access
  • part of private protected access modifier

• protected: goes to the protected access modifier

  • protected access
  • part of protected internal access
  • part of private protected access

This was previously handled by @davidwengier in dotnet/roslyn#46343.

The issue doesn't mention colon (:), which I think is currently not handled correctly (inheritance vs ternary operator)

[davidwengier]

Thanks @Youssef1313 good catch. I've added checkboxes to the OP, and will try to keep things up to date

[TheSench]

More items that are already covered:

dotnet/roslyn#46343

internal: destination is the page for internal access.

• internal access
• part of protected internal access

Pre-exists Github

where: already has separate pages for both usages

• where LINQ query expression
• where generic constraint

[Youssef1313]

There is also > for generics. Currently pressing F1 on it redirects here.

FYI @davidwengier

[Youssef1313]

< and > are being handled in dotnet/roslyn#60156.
The same PR also handles different contexts of = (assignment expression vs parameter default value vs property initializer)