Add XML comments to public members and fix formatting (#42)

tests/NetEscapades.EnumGenerators.Tests/Snapshots/EnumGeneratorTests.CanGenerateEnumExtensionsInChildNamespace.verified.txt

@@ -1,4 +1,4 @@
-//------------------------------------------------------------------------------
+//------------------------------------------------------------------------------
 // <auto-generated>
 //     This code was generated by the NetEscapades.EnumGenerators source generator
 //
@@ -14,6 +14,9 @@ using System;
 
 namespace MyTestNameSpace
 {
+    /// <summary>
+    /// Extension methods for <see cref="MyTestNameSpace.MyEnum" />
+    /// </summary>
     public static partial class MyEnumExtensions
     {
         /// <summary>
@@ -22,6 +25,14 @@ namespace MyTestNameSpace
         /// </summary>
         public const int Length = 2;
 
+        /// <summary>
+        /// Returns the string representation of the <see cref="MyTestNameSpace.MyEnum"/> value.
+        /// If the attribute is decorated with a <see cref="System.ComponentModel.DataAnnotations.DisplayAttribute"/>, then
+        /// uses the provided value. Otherwise uses the name of the member, equivalent to
+        /// calling <c>ToString()</c> on <paramref name="value"/>.
+        /// </summary>
+        /// <param name="value">The value to retrieve the string value for</param>
+        /// <returns>The string representation of the value</returns>
         public static string ToStringFast(this MyTestNameSpace.MyEnum value)
             => value switch
             {
@@ -30,6 +41,11 @@ namespace MyTestNameSpace
                 _ => value.ToString(),
             };
 
+        /// <summary>
+        /// Returns a boolean telling whether the given enum value exists in the enumeration.
+        /// </summary>
+        /// <param name="value">The value to check if it's defined</param>
+        /// <returns><c>true</c> if the value exists in the enumeration, <c/>false</c> otherwise</returns>
        public static bool IsDefined(MyTestNameSpace.MyEnum value)
             => value switch
             {
@@ -38,8 +54,22 @@ namespace MyTestNameSpace
                 _ => false,
             };
 
+        /// <summary>
+        /// Returns a boolean telling whether an enum with the given name exists in the enumeration.
+        /// </summary>
+        /// <param name="name">The name to check if it's defined</param>
+        /// <returns><c>true</c> if a member with the name exists in the enumeration, <c/>false</c> otherwise</returns>
         public static bool IsDefined(string name) => IsDefined(name, allowMatchingMetadataAttribute: false);
 
+        /// <summary>
+        /// Returns a boolean telling whether an enum with the given name exists in the enumeration,
+        /// or if a member decorated with a <see cref="System.ComponentModel.DataAnnotations.DisplayAttribute"/>
+        /// with the required name exists.
+        /// </summary>
+        /// <param name="name">The name to check if it's defined</param>
+        /// <param name="allowMatchingMetadataAttribute">If <c>true</c>, considers the value of metadata attributes,otherwise ignores them</param>
+        /// <returns><c>true</c> if a member with the name exists in the enumeration, or a member is decorated
+        /// with a <see cref="System.ComponentModel.DataAnnotations.DisplayAttribute"/> with the name, <c/>false</c> otherwise</returns>
         public static bool IsDefined(string name, bool allowMatchingMetadataAttribute)
         {
             return name switch
@@ -51,15 +81,23 @@ namespace MyTestNameSpace
         }
 
 #if NETCOREAPP && !NETCOREAPP2_0 && !NETCOREAPP1_1 && !NETCOREAPP1_0
+        /// <summary>
+        /// Returns a boolean telling whether an enum with the given name exists in the enumeration
+        /// </summary>
+        /// <param name="name">The name to check if it's defined</param>
+        /// <returns><c>true</c> if a member with the name exists in the enumeration, <c/>false</c> otherwise</returns>
         public static bool IsDefined(in ReadOnlySpan<char> name) => IsDefined(name, allowMatchingMetadataAttribute: false);
 
         /// <summary>
-        /// Slower then the <see cref="IsDefined(string, bool)",
-        /// bacause the <c>ReadOnlySpan<char></c> can't be cached like a string, tho it doesn't allocate memory./>
+        /// Returns a boolean telling whether an enum with the given name exists in the enumeration,
+        /// or optionally if a member decorated with a <see cref="System.ComponentModel.DataAnnotations.DisplayAttribute"/>
+        /// with the required name exists.
+        /// Slower then the <see cref="IsDefined(string, bool)" /> overload, but doesn't allocate memory./>
         /// </summary>
-        /// <param name="name"></param>
-        /// <param name="allowMatchingMetadataAttribute"></param>
-        /// <returns><c>true</c> if defined, otherwise <c>false</c></returns>
+        /// <param name="name">The name to check if it's defined</param>
+        /// <param name="allowMatchingMetadataAttribute">If <c>true</c>, considers the value of metadata attributes,otherwise ignores them</param>
+        /// <returns><c>true</c> if a member with the name exists in the enumeration, or a member is decorated
+        /// with a <see cref="System.ComponentModel.DataAnnotations.DisplayAttribute"/> with the name, <c/>false</c> otherwise</returns>
         public static bool IsDefined(in ReadOnlySpan<char> name, bool allowMatchingMetadataAttribute)
         {
             return name switch
@@ -71,6 +109,18 @@ namespace MyTestNameSpace
         }
 #endif
 
+        /// <summary>
+        /// Converts the string representation of the name or numeric value of
+        /// an <see cref="MyTestNameSpace.MyEnum" /> to the equivalent instance.
+        /// The return value indicates whether the conversion succeeded.
+        /// </summary>
+        /// <param name="name">The case-sensitive string representation of the enumeration name or underlying value to convert</param>
+        /// <param name="value">When this method returns, contains an object of type 
+        /// <see cref="MyTestNameSpace.MyEnum" /> whose
+        /// value is represented by <paramref name="value"/> if the parse operation succeeds.
+        /// If the parse operation fails, contains the default value of the underlying type
+        /// of <see cref="MyTestNameSpace.MyEnum" />. This parameter is passed uninitialized.</param>
+        /// <returns><c>true</c> if the value parameter was converted successfully; otherwise, <c>false</c>.</returns>
         public static bool TryParse(
 #if NETCOREAPP3_0_OR_GREATER
             [System.Diagnostics.CodeAnalysis.NotNullWhen(true)]
@@ -79,6 +129,19 @@ namespace MyTestNameSpace
             out MyTestNameSpace.MyEnum value)
             => TryParse(name, out value, false, false);
 
+        /// <summary>
+        /// Converts the string representation of the name or numeric value of
+        /// an <see cref="MyTestNameSpace.MyEnum" /> to the equivalent instance.
+        /// The return value indicates whether the conversion succeeded.
+        /// </summary>
+        /// <param name="name">The string representation of the enumeration name or underlying value to convert</param>
+        /// <param name="value">When this method returns, contains an object of type 
+        /// <see cref="MyTestNameSpace.MyEnum" /> whose
+        /// value is represented by <paramref name="value"/> if the parse operation succeeds.
+        /// If the parse operation fails, contains the default value of the underlying type
+        /// of <see cref="MyTestNameSpace.MyEnum" />. This parameter is passed uninitialized.</param>
+        /// <param name="ignoreCase"><c>true</c> to read value in case insensitive mode; <c>false</c> to read value in case sensitive mode.</param>
+        /// <returns><c>true</c> if the value parameter was converted successfully; otherwise, <c>false</c>.</returns>
         public static bool TryParse(
 #if NETCOREAPP3_0_OR_GREATER
             [System.Diagnostics.CodeAnalysis.NotNullWhen(true)]
@@ -88,6 +151,21 @@ namespace MyTestNameSpace
             bool ignoreCase) 
             => TryParse(name, out value, ignoreCase, false);
 
+        /// <summary>
+        /// Converts the string representation of the name or numeric value of
+        /// an <see cref="MyTestNameSpace.MyEnum" /> to the equivalent instance.
+        /// The return value indicates whether the conversion succeeded.
+        /// </summary>
+        /// <param name="name">The string representation of the enumeration name or underlying value to convert</param>
+        /// <param name="value">When this method returns, contains an object of type 
+        /// <see cref="MyTestNameSpace.MyEnum" /> whose
+        /// value is represented by <paramref name="value"/> if the parse operation succeeds.
+        /// If the parse operation fails, contains the default value of the underlying type
+        /// of <see cref="MyTestNameSpace.MyEnum" />. This parameter is passed uninitialized.</param>
+        /// <param name="ignoreCase"><c>true</c> to read value in case insensitive mode; <c>false</c> to read value in case sensitive mode.</param>
+        /// <param name="allowMatchingMetadataAttribute">If <c>true</c>, considers the value included in metadata attributes such as
+        /// <see cref="System.ComponentModel.DataAnnotations.DisplayAttribute"/> when parsing, otherwise only considers the member names.</param>
+        /// <returns><c>true</c> if the value parameter was converted successfully; otherwise, <c>false</c>.</returns>
         public static bool TryParse(
 #if NETCOREAPP3_0_OR_GREATER
             [System.Diagnostics.CodeAnalysis.NotNullWhen(true)]
@@ -136,6 +214,18 @@ namespace MyTestNameSpace
         }
 
 #if NETCOREAPP && !NETCOREAPP2_0 && !NETCOREAPP1_1 && !NETCOREAPP1_0
+        /// <summary>
+        /// Converts the span representation of the name or numeric value of
+        /// an <see cref="MyTestNameSpace.MyEnum" /> to the equivalent instance.
+        /// The return value indicates whether the conversion succeeded.
+        /// </summary>
+        /// <param name="name">The span representation of the enumeration name or underlying value to convert</param>
+        /// <param name="value">When this method returns, contains an object of type 
+        /// <see cref="MyTestNameSpace.MyEnum" /> whose
+        /// value is represented by <paramref name="value"/> if the parse operation succeeds.
+        /// If the parse operation fails, contains the default value of the underlying type
+        /// of <see cref="MyTestNameSpace.MyEnum" />. This parameter is passed uninitialized.</param>
+        /// <returns><c>true</c> if the value parameter was converted successfully; otherwise, <c>false</c>.</returns>
         public static bool TryParse(
 #if NETCOREAPP3_0_OR_GREATER
             [System.Diagnostics.CodeAnalysis.NotNullWhen(true)]
@@ -144,6 +234,19 @@ namespace MyTestNameSpace
             out MyTestNameSpace.MyEnum value)
             => TryParse(name, out value, false, false);
 
+        /// <summary>
+        /// Converts the span representation of the name or numeric value of
+        /// an <see cref="MyTestNameSpace.MyEnum" /> to the equivalent instance.
+        /// The return value indicates whether the conversion succeeded.
+        /// </summary>
+        /// <param name="name">The span representation of the enumeration name or underlying value to convert</param>
+        /// <param name="value">When this method returns, contains an object of type 
+        /// <see cref="MyTestNameSpace.MyEnum" /> whose
+        /// value is represented by <paramref name="value"/> if the parse operation succeeds.
+        /// If the parse operation fails, contains the default value of the underlying type
+        /// of <see cref="MyTestNameSpace.MyEnum" />. This parameter is passed uninitialized.</param>
+        /// <param name="ignoreCase"><c>true</c> to read value in case insensitive mode; <c>false</c> to read value in case sensitive mode.</param>
+        /// <returns><c>true</c> if the value parameter was converted successfully; otherwise, <c>false</c>.</returns>
         public static bool TryParse(
 #if NETCOREAPP3_0_OR_GREATER
             [System.Diagnostics.CodeAnalysis.NotNullWhen(true)]
@@ -154,14 +257,20 @@ namespace MyTestNameSpace
             => TryParse(name, out value, ignoreCase, false);
 
         /// <summary>
-        /// Slower then the <see cref="TryParse(string, out MyTestNameSpace.MyEnum, bool, bool)"/>,
-        /// bacause the <c>ReadOnlySpan<char></c> can't be cached like a string, tho it doesn't allocate memory./>
+        /// Converts the span representation of the name or numeric value of
+        /// an <see cref="MyTestNameSpace.MyEnum" /> to the equivalent instance.
+        /// The return value indicates whether the conversion succeeded.
         /// </summary>
-        /// <param name="name"></param>
-        /// <param name="result"></param>
-        /// <param name="ignoreCase"></param>
-        /// <param name="allowMatchingMetadataAttribute"></param>
-        /// <returns></returns>
+        /// <param name="name">The span representation of the enumeration name or underlying value to convert</param>
+        /// <param name="result">When this method returns, contains an object of type 
+        /// <see cref="MyTestNameSpace.MyEnum" /> whose
+        /// value is represented by <paramref name="result"/> if the parse operation succeeds.
+        /// If the parse operation fails, contains the default value of the underlying type
+        /// of <see cref="MyTestNameSpace.MyEnum" />. This parameter is passed uninitialized.</param>
+        /// <param name="ignoreCase"><c>true</c> to read value in case insensitive mode; <c>false</c> to read value in case sensitive mode.</param>
+        /// <param name="allowMatchingMetadataAttribute">If <c>true</c>, considers the value included in metadata attributes such as
+        /// <see cref="System.ComponentModel.DataAnnotations.DisplayAttribute"/> when parsing, otherwise only considers the member names.</param>
+        /// <returns><c>true</c> if the value parameter was converted successfully; otherwise, <c>false</c>.</returns>
         public static bool TryParse(
 #if NETCOREAPP3_0_OR_GREATER
             [System.Diagnostics.CodeAnalysis.NotNullWhen(true)]
@@ -210,6 +319,13 @@ namespace MyTestNameSpace
         }
 #endif
 
+        /// <summary>
+        /// Retrieves an array of the values of the members defined in
+        /// <see cref="MyTestNameSpace.MyEnum" />.
+        /// Note that this returns a new array with every invocation, so
+        /// should be cached if appropriate.
+        /// </summary>
+        /// <returns>An array of the values defined in <see cref="MyTestNameSpace.MyEnum" /></returns>
         public static MyTestNameSpace.MyEnum[] GetValues()
         {
             return new[]
@@ -219,6 +335,13 @@ namespace MyTestNameSpace
             };
         }
 
+        /// <summary>
+        /// Retrieves an array of the names of the members defined in
+        /// <see cref="MyTestNameSpace.MyEnum" />.
+        /// Note that this returns a new array with every invocation, so
+        /// should be cached if appropriate.
+        /// </summary>
+        /// <returns>An array of the names of the members defined in <see cref="MyTestNameSpace.MyEnum" /></returns>
         public static string[] GetNames()
         {
             return new[]