Updated docs and doc comments (#31)

* Enabled XML generation for multiple projects to allow DocFx to pick up the generated results.

Author: smaillet

docfx/CodeAnalysis/api/index.md

@@ -1,6 +1,21 @@
 # About
-Ubiquity.NET.CodeAnalysis contains general extensions for .NET. 
+Ubiquity.NET.CodeAnlysis.Utils contains support for Roslyn components doing code analysis,
+fixes, and source generation within the Roslyn compiler.
 
 ## Key support
-TBD
 
+* Support for caching of generation scan results (via `IEquatable<T>`)
+* Debug diagnostic asserts for class vs. struct trade-offs 
+* Capturing symbol information in a cacheable fashion
+* Generation of diagnostics for issues detected in a generator<a href="#footnote_1"><sup>1</sup></a>
+* Create a `SourceText` from a `StringBuilder` to allow generation to remain independent of
+  the Roslyn CodeAnalysis types.
+
+------
+<sup id="footnote_1">1</sup> Generators creating diagnostics is generally not recommended.
+The official
+[Incremental Generators](https://github.com/dotnet/roslyn/blob/main/docs/features/incremental-generators.cookbook.md)
+cook book recommends against it. A generator should generally ignore invalid input and fail
+silently by ignoring the problem. An analyzer can produce the diagnostics for problems. At
+most a generator can use this support to report critical problems that prevent the generator
+from running at all.

docfx/CodeAnalysis/index.md

@@ -1,4 +1,24 @@
 # About
-Ubiquity.NET.CodeAnlysis.Utils contains support for CodeAnalysis
+The Ubiquity.NET.CodeAnalysis.Utils package contains support for building Roslyn analyzers,
+fixers, and source generator. As such it specifically targets .NET Standard 2.0 and has no
+dependencies on anything targeting a later runtime. If an analyzer (or any Roslyn extension)
+depends on this package the dependencies for the package must be included in the extension's
+package.
 
 ## Key support
+
+* Support for caching of generation scan results (via `IEquatable<T>`)
+* Debug diagnostic asserts for class vs. struct trade-offs 
+* Capturing symbol information in a cacheable fashion
+* Generation of diagnostics for issues detected in a generator<a href="#footnote_1"><sup>1</sup></a>
+* Create a `SourceText` from a `StringBuilder` to allow generation to remain independent of
+  the Roslyn CodeAnalysis types.
+
+------
+<sup id="footnote_1">1</sup> Generators creating diagnostics is generally not recommended.
+The official
+[Incremental Generators](https://github.com/dotnet/roslyn/blob/main/docs/features/incremental-generators.cookbook.md)
+cook book recommends against it. A generator should normally ignore invalid input and fail
+silently by ignoring the problem. An analyzer can produce the diagnostics for problems. At
+most a generator can use this support to report critical problems that prevent the generator
+from running at all.

docfx/IgnoredWords.dic

@@ -1,6 +1,7 @@
 antlr
 arity
 bool
+cacheable
 initializer
 interop
 marshalling

docfx/documentation.msbuildproj

@@ -65,12 +65,19 @@
   </ItemGroup>
 
   <ItemGroup>
-    <!--Everything in the SrcGeneration sub-folders except the API folder as that contains generated files -->
+    <!--Everything in the SrcGeneration  test utilities sub-folders except the API folder as that contains generated files -->
     <None Include="src-gen-test-utils/**" Exclude="src-gen-test-utils/api/**" />
     <!-- Explicitly call out the non-generated files in the API folder-->
     <None Include="src-gen-test-utils/api/index.md" />
   </ItemGroup>
 
+  <ItemGroup>
+    <!--Everything in the CodeAnalysis utilities sub-folders except the API folder as that contains generated files -->
+    <None Include="CodeAnalysis/**" Exclude="CodeAnalysis/api/**" />
+    <!-- Explicitly call out the non-generated files in the API folder-->
+    <None Include="CodeAnalysis/api/index.md" />
+  </ItemGroup>
+
   <Target Name="AlwaysRun" BeforeTargets="AfterBuild">
     <Message Importance="High" Text="NOTE: Building $(MSBuildProjectFile) does NOTHING, docs are built using the docfx tool. This project is simply a convenient placeholder for organizing/editing files" />
   </Target>

src/Ubiquity.NET.ANTLR.Utils/LocationExtensions.cs

@@ -58,12 +58,10 @@ public static SourceRange GetSourceRange( this IToken token )
         {
             ArgumentNullException.ThrowIfNull( token );
 
-            // TODO: Q: Should this account for a newline in the token?
-            //       A: Probably not, as a token can't span a newline.
             return new SourceRange(
                 new(token.Line, token.Column, token.StartIndex),
                 new(token.Line, token.Column + token.Text.Length, token.StopIndex)
-                );
+            );
         }
     }
 }

src/Ubiquity.NET.ANTLR.Utils/ReadMe.md

@@ -13,7 +13,7 @@ This library provides general extensions to ANTLR including adapter bindings for
   `Ubiquity.NET.Runtime.IParseErrorListener`.
   - This allows building consumers that deal with errors and remain independent of the
     parsing technology.
-* Extension functions that provides commonly used support for ANTLR
+* Extension functions that provide commonly used support for ANTLR
     -  Get a character interval from a ParserRuleContext with support for the standard EOF
        rule.
     - Gets the source stream from an IRecognizer

src/Ubiquity.NET.CodeAnalysis.Utils/DebugAssert.cs

@@ -8,15 +8,15 @@ namespace Ubiquity.NET.CodeAnalysis.Utils
     /// <summary>Utility class to support Debug asserts</summary>
     public static class DebugAssert
     {
-        /// <summary>Tests if a structure size is < 16 bytes and generates a debug assertion if not</summary>
+        /// <summary>Tests if a structure size is &lt; 16 bytes and generates a debug assertion if not</summary>
         /// <typeparam name="T">Type of the struct to test</typeparam>
         /// <remarks>
         /// <para>This uses a runtime debug assert as it isn't possible to know the size at compile time of a managed struct.
         /// The `sizeof` doesn't apply for anything with a managed reference or a native pointer sized member
         /// as such sizes depend on the actual runtime used.</para>
         /// <note type="important">
-        /// This function ONLY operates in a debug build. That is, this is the compiler will elide calls to this method
-        /// at the call site unless the "DEBUG" symbol is defined as it has a <see cref="ConditionalAttribute"/> attached to it.
+        /// This function ONLY operates in a debug build. That is, the compiler will elide calls to this method
+        /// at the <em><b>call site</b></em> unless the "DEBUG" symbol is defined as it has a <see cref="ConditionalAttribute"/> attached to it.
         /// </note>
         /// </remarks>
         /// <seealso href="https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/choosing-between-class-and-struct"/>

src/Ubiquity.NET.CodeAnalysis.Utils/DiagnosticInfo.cs

@@ -82,7 +82,7 @@ public override bool Equals( object obj )
         /// <inheritdoc/>
         public override int GetHashCode( )
         {
-            // sadly this will re-hash the hashcode computed for the structure, but there is no way
+            // sadly this will re-hash the hash code computed for the structure, but there is no way
             // to combine the result of a hash with other things. (The overload of Add(int) is private)
             // The generic Add<T>() will call the type's GetHashCode() and ignores the implementation of
             // IStructuralEquatable.

src/Ubiquity.NET.CodeAnalysis.Utils/EquatableAttributeData.cs

@@ -44,7 +44,7 @@ public EquatableAttributeData( AttributeData data )
 
         /// <summary>Gets the constant for a named argument</summary>
         /// <param name="argName">Name of the argument to fetch</param>
-        /// <returns>Optional value for the named argument (<see cref="Optional.HasValue"/> is false if <paramref name="argName"/> isn't provided)</returns>
+        /// <returns>Optional value for the named argument (<see cref="Optional{T}.HasValue"/> is false if <paramref name="argName"/> isn't provided)</returns>
         public Optional<StructurallyEquatableTypedConstant> GetNamedArgValue( string argName )
         {
             return NamedArguments.TryGetValue( argName, out StructurallyEquatableTypedConstant typedConst )
@@ -76,7 +76,7 @@ public Optional<T> GetNamedArgValue<T>( string name )
         /// <param name="argName">Name of the attribute argument</param>
         /// <returns><see cref="Optional{T}"/> for the array of values</returns>
         /// <remarks>
-        /// The <paramref name="name"/> name may not be specified in which case the result
+        /// The <paramref name="argName"/> name may not be specified in which case the result
         /// will have not value (<see cref="Optional{T}.HasValue"/> is false). It is also
         /// possible that it was specified AND that the value is null (if T is a nullable type
         /// or a default instance if it is not.) Thus it is important to examine the return
@@ -139,6 +139,8 @@ public override bool Equals( object obj )
                 && Equals( other );
         }
 
+        /// <summary>Implicit cast from <see cref="AttributeData"/></summary>
+        /// <param name="data">Dat to convert</param>
         [SuppressMessage( "Usage", "CA2225:Operator overloads have named alternates", Justification = "Implicit cast for public constructor" )]
         public static implicit operator EquatableAttributeData( AttributeData data )
         {

src/Ubiquity.NET.CodeAnalysis.Utils/EquatableAttributeDataCollection.cs

@@ -83,7 +83,7 @@ public override int GetHashCode( )
 
         /// <summary>Gets a sequence of the names of all values.</summary>
         /// <remarks>
-        /// These names are keys for the values used in <see cref="this[]"/> and
+        /// These names are keys for the values used in <see cref="this[NamespaceQualifiedName]"/> and
         /// <see cref="TryGetValue(NamespaceQualifiedName, out EquatableAttributeData)"/>.
         /// </remarks>
         public IEnumerable<NamespaceQualifiedName> Keys => InnerDictionary.Keys;
@@ -104,6 +104,8 @@ public bool TryGetValue( NamespaceQualifiedName key, [MaybeNullWhen( false )] ou
             return InnerDictionary.TryGetValue( key, out item );
         }
 
+        /// <summary>Implicit cast from <see cref="ImmutableArray{T}"/></summary>
+        /// <param name="attributes">Immutable array of attribute data to form a keyed collection from</param>
         [SuppressMessage( "Usage", "CA2225:Operator overloads have named alternates", Justification = "Simple wrapper over public constructor" )]
         public static implicit operator EquatableAttributeDataCollection( ImmutableArray<EquatableAttributeData> attributes )
         {