[WIP] Update F1 keywords for tokens with multiple uses

[Copilot]

Thanks for assigning this issue to me. I'm starting to work on it and will keep this PR's description up to date as I form a plan and make progress.

Original issue description:

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

Fixes #20799.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

---

Internal previews

📄 File	🔗 Preview link
docs/csharp/language-reference/builtin-types/enum.md	docs/csharp/language-reference/builtin-types/enum
docs/csharp/language-reference/builtin-types/ref-struct.md	docs/csharp/language-reference/builtin-types/ref-struct
docs/csharp/language-reference/keywords/extension.md	docs/csharp/language-reference/keywords/extension
docs/csharp/language-reference/keywords/from-clause.md	docs/csharp/language-reference/keywords/from-clause
docs/csharp/language-reference/keywords/in-generic-modifier.md	docs/csharp/language-reference/keywords/in-generic-modifier
docs/csharp/language-reference/keywords/join-clause.md	docs/csharp/language-reference/keywords/join-clause
docs/csharp/language-reference/keywords/method-parameters.md	docs/csharp/language-reference/keywords/method-parameters
docs/csharp/language-reference/keywords/new-constraint.md	docs/csharp/language-reference/keywords/new-constraint
docs/csharp/language-reference/keywords/new-modifier.md	docs/csharp/language-reference/keywords/new-modifier
docs/csharp/language-reference/keywords/out-generic-modifier.md	docs/csharp/language-reference/keywords/out-generic-modifier

[BillWagner]

Hi @copilot Can you start working on this again?

[Copilot]

Hi @copilot Can you start working on this again?

I'll start working on the remaining F1 keywords for tokens with multiple uses. I'll focus on the uncompleted items in the checklist: enum, in, new, out, ref, this, and using.

[BillWagner]

This is a good start but it needs changes.

An f1_keyword can only have one target file. Where a keyword (like in) has multiple uses, the file for that keyword (for example "in.md") should have the appropriate f1 keyword tag. The text of that file should link to articles on all the different uses of that keyword.

[BillWagner]

This line should be removed. There's a different target for ref. Check the file "ref.md" to see if it's got a link to this file.

[Copilot]

Removed the conflicting ref_CSharpKeyword from ref-struct.md. The ref.md file already has the F1 keyword and properly links to this file. (6077675)

[BillWagner]

This should be removed. The this keyword targets "this.md". Check that file to see if it links to this file.

[Copilot]

Removed the conflicting this_CSharpKeyword from extension.md. The this.md file already has the F1 keyword and properly links to this file. (6077675)

[BillWagner]

Remove this. The in keyword already targets "in.md". Make sure there's a link in that file to this one.

[Copilot]

Removed the conflicting in_CSharpKeyword from from-clause.md. The in.md file already has the F1 keyword and properly links to this file. (6077675)

[BillWagner]

Same comment about in_CSharpKeyword

[Copilot]

Removed the conflicting in_CSharpKeyword from in-generic-modifier.md. The in.md file already has the F1 keyword and properly links to this file. (6077675)

[BillWagner]

Same comment.

[Copilot]

Removed the conflicting in_CSharpKeyword from join-clause.md. The in.md file already has the F1 keyword and properly links to this file. (6077675)

[Copilot]

This is a good start but it needs changes.

An f1_keyword can only have one target file. Where a keyword (like in) has multiple uses, the file for that keyword (for example "in.md") should have ...

You're absolutely right. I've removed all the conflicting F1 keywords from the specific usage files. Now each F1 keyword has only one target file - the main keyword file (like in.md, ref.md, this.md, etc.) which properly links to all the specific usage files. (6077675)

[BillWagner]

Closing this as it's going in the wrong direction.