Repository navigation
Update F1 keywords for tokens with multiple uses #20799
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
switchstatement - default operator or default literal.
- default label of a
-
enum: destination describes declaring an enum.- declare an
enumtype - generic constraint where the base type must be an
enum(derived fromSystem.Enum)
- declare an
-
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
inas part of aforeachstatement.- part of a
fromclause in a LINQ query expression - part of a
joinclause in a LINQ query expression
-
internal: destination is the page forinternalaccess.internalaccess- part of
protected internalaccess
-
new: goes to thenewexpression page, with a link to the method modifier.- new expressions
- new method declaration modifier
newconstraint 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 toprivateaccess modifierprivateaccess- part of
private protectedaccess modifier
-
protected: goes to the protected access modifierprotectedaccess- part of
protected internalaccess - part of
private protectedaccess
-
ref: goes to the page forrefparameter / argument modifier,refreturn andreflocal. Page has link toref structusage.refparameter / argument modifierrefreturn valuereflocal variable.refstruct declaration
-
staticpage goes to static modifier on class, field, method, local function, or lambda declarationstaticmodifier.- part of the
using staticdirective.
-
struct: page goes tostructdeclarations (which includesref structandreadonly struct.- declare a struct
- specify the
structconstraint on a generic type parameter.
-
thispage is forthisreferring to the current instance of a type- refer to the current instance of a type
- parameter modifier for first argument of an extension method
-
usinggoes to a landing page for different uses.usingdirective-
using staticdirective usingstatement
-
partial: already has separate pages for type and methodpartialtypepartialmethod
-
where: already has separate pages for both usageswhereLINQ query expressionwheregeneric 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.
Activity
Youssef1313 commentedon Oct 6, 2020
@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 commentedon Oct 6, 2020
@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 commentedon Oct 6, 2020
@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 commentedon Oct 7, 2020
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 commentedon Oct 12, 2020
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 commentedon Oct 13, 2020
Thanks @Youssef1313 good catch. I've added checkboxes to the OP, and will try to keep things up to date
TheSench commentedon Oct 24, 2020
More items that are already covered:
dotnet/roslyn#46343
Pre-exists Github
14 remaining items
BillWagner commentedon Jul 3, 2025
Putting this back in the backlog. Copilot didn't understand the instructions well.