From 7e46750fff2a57ce72381579dab50992a884b2a5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Amaury=20Lev=C3=A9?= <evangelink@gmail.com>
Date: Thu, 12 Dec 2019 10:50:27 +0100
Subject: [PATCH] Add xml documentation for IsKind and Kind extension methods

---
 .../CSharp/Portable/CSharpExtensions.cs       | 44 ++++++++++++++++++-
 .../Portable/VisualBasicExtensions.vb         | 43 ++++++++++--------
 2 files changed, 66 insertions(+), 21 deletions(-)

diff --git a/src/Compilers/CSharp/Portable/CSharpExtensions.cs b/src/Compilers/CSharp/Portable/CSharpExtensions.cs
index 8c44283402f..06da90f727a 100644
--- a/src/Compilers/CSharp/Portable/CSharpExtensions.cs
+++ b/src/Compilers/CSharp/Portable/CSharpExtensions.cs
@@ -6,29 +6,52 @@
 using System.Threading;
 using Microsoft.CodeAnalysis.CSharp;
 using Microsoft.CodeAnalysis.CSharp.Syntax;
-using Microsoft.CodeAnalysis.CSharp.Symbols;
-using Microsoft.CodeAnalysis.Syntax;
 using Microsoft.CodeAnalysis.Operations;
+using Microsoft.CodeAnalysis.Syntax;
 
 namespace Microsoft.CodeAnalysis
 {
     public static class CSharpExtensions
     {
+        /// <summary>
+        /// Determines if <see cref="SyntaxToken"/> is of a specified kind.
+        /// </summary>
+        /// <param name="token">The source token.</param>
+        /// <param name="kind">The syntax kind to test for.</param>
+        /// <returns><c>true</c> if token is of specified kind; <c>false</c> otherwise.</returns>
         public static bool IsKind(this SyntaxToken token, SyntaxKind kind)
         {
             return token.RawKind == (int)kind;
         }
 
+        /// <summary>
+        /// Determines if <see cref="SyntaxTrivia"/> is of a specified kind.
+        /// </summary>
+        /// <param name="trivia">The source trivia.</param>
+        /// <param name="kind">The syntax kind to test for.</param>
+        /// <returns><c>true</c> if trivia is of specified kind; <c>false</c> otherwise.</returns>
         public static bool IsKind(this SyntaxTrivia trivia, SyntaxKind kind)
         {
             return trivia.RawKind == (int)kind;
         }
 
+        /// <summary>
+        /// Determines if <see cref="SyntaxNode"/> is of a specified kind.
+        /// </summary>
+        /// <param name="node">The source node.</param>
+        /// <param name="kind">The syntax kind to test for.</param>
+        /// <returns><c>true</c> if node is of specified kind; <c>false</c> otherwise.</returns>
         public static bool IsKind(this SyntaxNode node, SyntaxKind kind)
         {
             return node?.RawKind == (int)kind;
         }
 
+        /// <summary>
+        /// Determines if <see cref="SyntaxNodeOrToken"/> is of a specified kind.
+        /// </summary>
+        /// <param name="nodeOrToken">The source node or token.</param>
+        /// <param name="kind">The syntax kind to test for.</param>
+        /// <returns><c>true</c> if node or token is of specified kind; <c>false</c> otherwise.</returns>
         public static bool IsKind(this SyntaxNodeOrToken nodeOrToken, SyntaxKind kind)
         {
             return nodeOrToken.RawKind == (int)kind;
@@ -139,6 +162,11 @@ namespace Microsoft.CodeAnalysis.CSharp
 {
     public static class CSharpExtensions
     {
+        /// <summary>
+        /// Determines if the given raw kind value belongs to the C# <see cref="SyntaxKind"/> enumeration.
+        /// </summary>
+        /// <param name="rawKind">The raw value to test.</param>
+        /// <returns><c>true</c> when the raw value belongs to the C# syntax kind; <c>false</c> otherwise.</returns>
         internal static bool IsCSharpKind(int rawKind)
         {
             const int FirstVisualBasicKind = (int)SyntaxKind.List + 1;
@@ -148,24 +176,36 @@ internal static bool IsCSharpKind(int rawKind)
             return unchecked((uint)(rawKind - FirstVisualBasicKind)) > (FirstCSharpKind - 1 - FirstVisualBasicKind);
         }
 
+        /// <summary>
+        /// Returns <see cref="SyntaxKind"/> for <see cref="SyntaxToken"/> from <see cref="SyntaxToken.RawKind"/> property.
+        /// </summary>
         public static SyntaxKind Kind(this SyntaxToken token)
         {
             var rawKind = token.RawKind;
             return IsCSharpKind(rawKind) ? (SyntaxKind)rawKind : SyntaxKind.None;
         }
 
+        /// <summary>
+        /// Returns <see cref="SyntaxKind"/> for <see cref="SyntaxTrivia"/> from <see cref="SyntaxTrivia.RawKind"/> property.
+        /// </summary>
         public static SyntaxKind Kind(this SyntaxTrivia trivia)
         {
             var rawKind = trivia.RawKind;
             return IsCSharpKind(rawKind) ? (SyntaxKind)rawKind : SyntaxKind.None;
         }
 
+        /// <summary>
+        /// Returns <see cref="SyntaxKind"/> for <see cref="SyntaxNode"/> from <see cref="SyntaxNode.RawKind"/> property.
+        /// </summary>
         public static SyntaxKind Kind(this SyntaxNode node)
         {
             var rawKind = node.RawKind;
             return IsCSharpKind(rawKind) ? (SyntaxKind)rawKind : SyntaxKind.None;
         }
 
+        /// <summary>
+        /// Returns <see cref="SyntaxKind"/> for <see cref="SyntaxNode"/> from <see cref="SyntaxNodeOrToken.RawKind"/> property.
+        /// </summary>
         public static SyntaxKind Kind(this SyntaxNodeOrToken nodeOrToken)
         {
             var rawKind = nodeOrToken.RawKind;
diff --git a/src/Compilers/VisualBasic/Portable/VisualBasicExtensions.vb b/src/Compilers/VisualBasic/Portable/VisualBasicExtensions.vb
index 629342c9304..bf579208089 100644
--- a/src/Compilers/VisualBasic/Portable/VisualBasicExtensions.vb
+++ b/src/Compilers/VisualBasic/Portable/VisualBasicExtensions.vb
@@ -2,8 +2,6 @@
 
 Imports System.Collections.Immutable
 Imports System.Collections.ObjectModel
-Imports System.ComponentModel
-Imports System.IO
 Imports System.Runtime.CompilerServices
 Imports System.Runtime.InteropServices
 Imports System.Threading
@@ -20,42 +18,44 @@ Namespace Microsoft.CodeAnalysis
     Public Module VisualBasicExtensions
 
         ''' <summary>
-        ''' Determines if SyntaxTrivia is a specified kind.
+        ''' Determines if <see cref="SyntaxTrivia"/> is of a specified kind.
         ''' </summary>
-        '''<param name="trivia">The Source SyntaxTrivia.</param>
-        ''' <param name="kind">The SyntaxKind to test for.</param>
+        ''' <param name="trivia">The source trivia.</param>
+        ''' <param name="kind">The syntax kind to test for.</param>
+        ''' <returns><c>true</c> if triviq is of specified kind; <c>false</c> otherwise.</returns>
         <Extension>
         Public Function IsKind(trivia As SyntaxTrivia, kind As SyntaxKind) As Boolean
             Return trivia.RawKind = kind
         End Function
 
         ''' <summary>
-        ''' Determines if SyntaxToken is a specified kind.
+        ''' Determines if <see cref="SyntaxToken"/> is of a specified kind.
         ''' </summary>
-        '''<param name="token">The Source SyntaxToken.</param>
-        ''' <param name="kind">The SyntaxKind to test for.</param>
+        ''' <param name="token">The source token.</param>
+        ''' <param name="kind">The syntax kind to test for.</param>
+        ''' <returns><c>true</c> if token is of specified kind; <c>false</c> otherwise.</returns>
         <Extension>
         Public Function IsKind(token As SyntaxToken, kind As SyntaxKind) As Boolean
             Return token.RawKind = kind
         End Function
 
         ''' <summary>
-        ''' Determines if SyntaxNode is a specified kind.
+        ''' Determines if <see cref="SyntaxNode"/> is of a specified kind.
         ''' </summary>
-        ''' <param name="node">The Source SyntaxNode.</param>
-        ''' <param name="kind">The SyntaxKind to test for.</param>
-        ''' <returns>A boolean value if node is of specified kind; otherwise false.</returns>
+        ''' <param name="node">The Source node.</param>
+        ''' <param name="kind">The syntax kind  to test for.</param>
+        ''' <returns><c>true</c> if node is of specified kind; <c>false</c> otherwise.</returns>
         <Extension>
         Public Function IsKind(node As SyntaxNode, kind As SyntaxKind) As Boolean
             Return node IsNot Nothing AndAlso node.RawKind = kind
         End Function
 
         ''' <summary>
-        ''' Determines if a SyntaxNodeOrToken is a specified kind.
+        ''' Determines if <see cref="SyntaxNodeOrToken"/> is of a specified kind.
         ''' </summary>
-        ''' <param name="nodeOrToken">The source SyntaxNodeOrToken.</param>
-        ''' <param name="kind">The SyntaxKind to test for.</param>
-        ''' <returns>A boolean value if nodeOrToken is of specified kind; otherwise false.</returns>
+        ''' <param name="nodeOrToken">The source node or token.</param>
+        ''' <param name="kind">The syntax kind to test for.</param>
+        ''' <returns><c>true</c> if node or token is of specified kind; <c>false</c> otherwise.</returns>
         <Extension>
         Public Function IsKind(nodeOrToken As SyntaxNodeOrToken, kind As SyntaxKind) As Boolean
             Return nodeOrToken.RawKind = kind
@@ -164,6 +164,11 @@ End Namespace
 
 Namespace Microsoft.CodeAnalysis.VisualBasic
     Public Module VisualBasicExtensions
+        ''' <summary>
+        ''' Determines if the given raw kind value belongs to the Visual Basic <see cref="SyntaxKind"/> enumeration.
+        ''' </summary>
+        ''' <param name="rawKind">The raw value to test.</param>
+        ''' <returns><c>true</c> when the raw value belongs to the Visual Basic syntax kind; <c>false</c> otherwise.</returns>
         Friend Function IsVisualBasicKind(rawKind As Integer) As Boolean
             Const LastPossibleVisualBasicKind As Integer = 8192
 
@@ -171,7 +176,7 @@ Namespace Microsoft.CodeAnalysis.VisualBasic
         End Function
 
         ''' <summary>
-        ''' Returns <see cref="SyntaxKind"/> for <see cref="SyntaxTrivia"/> nodes.
+        ''' Returns <see cref="SyntaxKind"/> for <see cref="SyntaxTrivia"/> from <see cref="SyntaxTrivia.RawKind"/> property.
         ''' </summary>
         <Extension>
         Public Function Kind(trivia As SyntaxTrivia) As SyntaxKind
@@ -189,7 +194,7 @@ Namespace Microsoft.CodeAnalysis.VisualBasic
         End Function
 
         ''' <summary>
-        ''' Returns <see cref="SyntaxKind"/> for <see cref="SyntaxNode"/> from <see cref="SyntaxToken.RawKind"/> property.
+        ''' Returns <see cref="SyntaxKind"/> for <see cref="SyntaxNode"/> from <see cref="SyntaxNode.RawKind"/> property.
         ''' </summary>
         <Extension>
         Public Function Kind(node As SyntaxNode) As SyntaxKind
@@ -198,7 +203,7 @@ Namespace Microsoft.CodeAnalysis.VisualBasic
         End Function
 
         ''' <summary>
-        ''' Returns <see cref="SyntaxKind"/> for <see cref="SyntaxNodeOrToken"/> from <see cref="SyntaxToken.RawKind"/> property.
+        ''' Returns <see cref="SyntaxKind"/> for <see cref="SyntaxNodeOrToken"/> from <see cref="SyntaxNodeOrToken.RawKind"/> property.
         ''' </summary>
         <Extension>
         Public Function Kind(nodeOrToken As SyntaxNodeOrToken) As SyntaxKind
-- 
GitLab