Document SyntaxKinds

[Youssef1313]

After completing, it should fix dotnet/docs#20344 (this will be in a follow-up PR).

I added XML docs for the first few SyntaxKinds that I know, and kept a TODO for what I don't know.

Steps in my mind to complete this:

1. Review the currently few added summaries to see if you like the current wording or not.
2. After that, I'll complete documenting the whole enum, keeping TODOs for things I don't know.
3. Get feedback about the TODOs.
4. Addressing feedback.

[CyrusNajmabadi]

I don't think this is a good idea. The point is that the tokens don't represent anything. They're just tokens. A * could appear anywhere. The kind just tells you what textual form it has. You can tell what it means (i.e. if it's multiplication, or pointer type, or pointer deref, or funcptr, etc.) From the syntax and semantic operations available.

[CyrusNajmabadi]

Or, if you are going to doc the token kinds, they should be more like: represents a ! token

[Youssef1313]

@CyrusNajmabadi Thanks for review!
I'll update the tokens doc with your suggestion.

[Youssef1313]

@CyrusNajmabadi I've added more XML docs. Can you review what I've so far?

I think some keywords are for compiler usage only, but I'm not aware of all of them. Can you point to them to add a note indicating that?

[sharwell]

The closing </c> tags are currently malformed

mine

[sharwell]

@Youssef1313 Looks like we need a using directive for Microsoft.CodeAnalysis.CSharp.Syntax.

[Youssef1313]

@sharwell I'll add it when I continue documenting the rest of the enum. There are still many undocumented members. Or do you want to merge it as is now and open a follow-up a PR?

[sharwell]

@Youssef1313 I'd be fine with including the part we have here and looking at the next set in a follow-up.

[Youssef1313]

@sharwell, CI is failing here with error CS0234 The type or namespace name 'Syntax' does not exist in the namespace 'Microsoft.CodeAnalysis.CSharp'

This doesn't happen with me in Visual Studio.

[sharwell]

I believe this is occurring because SyntaxKinds.cs is linked into the code generation projects. You may need to wrap this in #if so it's only used for the Microsoft.CodeAnalysis.CSharp project.

[Youssef1313]

@sharwell, Microsoft.CodeAnalysis.CSharp.csproj doesn't currently contain any DefineConstants. Do I need to add a new one and use if for the #if directive?

[sharwell]

The other option is to use a fully-qualified cref attribute:

<see cref="T:Microsoft.CodeAnalysis.CSharp.Syntax.OmittedTypeArgumentSyntax"/>

[Youssef1313]

@sharwell, error CA1200: Avoid using cref tags with a prefix

Should I disable CA1200 in editorconfig? or in a ruleset file? or inline in the same file only? or a GlobalSuppressions.cs?

[sharwell]

error CA1200: Avoid using cref tags with a prefix

I would disable it in just this file using a #pragma, and update the default comment to also say that the usage is required since the file is included in projects that do not have access to the syntax nodes.

[333fred]

LGTM (commit 16). @dotnet/roslyn-compiler for a second review.

[jcouv]

LGTM Thanks (iteration 16)