Prep for release build of v10

* Bump version to RC status
* Lot's of updates to doc comments to work around yet another [DocFX bug](dotnet/docfx#6995)

BuildVersion.xml

@@ -2,6 +2,5 @@
     BuildMajor = "10"
     BuildMinor = "0"
     BuildPatch = "0"
-    PreReleaseName = "alpha"
-    PreReleaseNumber ="3"
+    PreReleaseName = "rc"
 />

Samples/Kaleidoscope/Chapter8/CodeGenerator.cs

@@ -8,7 +8,6 @@
 using System.Collections.Generic;
 using System.Diagnostics;
 using System.Linq;
-using System.Reflection;
 
 using Kaleidoscope.Grammar;
 using Kaleidoscope.Grammar.AST;

Samples/Kaleidoscope/Kaleidoscope.Parser/DynamicRuntimeState.cs

@@ -8,8 +8,6 @@
 
 using Antlr4.Runtime;
 
-using Kaleidoscope.Grammar.ANTLR;
-
 using Ubiquity.ArgValidators;
 
 using static Kaleidoscope.Grammar.ANTLR.KaleidoscopeLexer;

docfx/current/Ubiquity.NET.Llvm.Docfx.API.csproj

@@ -10,14 +10,14 @@
   <ItemGroup>
     <PackageReference Include="docfx.console" PrivateAssets="All" />
     <PackageReference Include="memberpage" PrivateAssets="All" GeneratePathProperty="true" />
-    <PackageReference Include="msdn.4.5.2" PrivateAssets="All" GeneratePathProperty="true" />
+    <!--PackageReference Include="msdn.4.5.2" PrivateAssets="All" GeneratePathProperty="true" /-->
   </ItemGroup>
 
   <Target Name="SetDocFxParameters" BeforeTargets="DocGenerateMetadata">
     <ItemGroup>
       <DocFxCrossRefMap Include="llvm-xref.yml" />
-      <DocFxCrossRefMap Include="$(Pkgmsdn_4_5_2)\content\msdn.4.5.2.zip" />
-      <DocFxCrossRefMap Include="$(Pkgmsdn_4_5_2)\content\namespaces.4.5.2.zip" />
+      <!--DocFxCrossRefMap Include="$(Pkgmsdn_4_5_2)\content\msdn.4.5.2.zip" />
+      <DocFxCrossRefMap Include="$(Pkgmsdn_4_5_2)\content\namespaces.4.5.2.zip" /-->
     </ItemGroup>
     <ItemGroup>
         <DocFxTemplate Include="statictoc" />

docfx/current/docfx.json

@@ -13,6 +13,7 @@
         }
     ],
     "build": {
+        "xrefService": ["https://xref.docs.microsoft.com/query?uid={uid}"],
         "content": [
             {
                 "files": [

src/Ubiquity.NET.Llvm.Tests/DebugInfo/DebugInfoBuilderTests.cs

@@ -4,17 +4,13 @@
 // </copyright>
 // -----------------------------------------------------------------------
 
-using System;
-using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.IO;
 using System.Linq;
 
 using Microsoft.VisualStudio.TestTools.UnitTesting;
 
 using Ubiquity.NET.Llvm.DebugInfo;
-using Ubiquity.NET.Llvm.Instructions;
-using Ubiquity.NET.Llvm.Values;
 using Ubiquity.NET.LlvmTests;
 
 namespace Ubiquity.NET.Llvm.Tests.DebugInfo

src/Ubiquity.NET.Llvm/BitcodeModule.cs

@@ -25,10 +25,6 @@
 namespace Ubiquity.NET.Llvm
 {
     /// <summary>Enumeration to indicate the behavior of module level flags metadata sharing the same name in a <see cref="BitcodeModule"/></summary>
-    [SuppressMessage( "Microsoft.Naming"
-                    , "CA1726:UsePreferredTerms"
-                    , MessageId = "Flag"
-                    , Justification = "Enum for the behavior of the LLVM ModuleFlag (Flag in middle doesn't imply the enum is Bit Flags)" )]
     [SuppressMessage( "Design", "CA1027:Mark enums with FlagsAttribute", Justification = "It isn't a flags enum" )]
     public enum ModuleFlagBehavior
     {
@@ -288,17 +284,13 @@ public void AppendInlineAsm( string asm )
             LLVMAppendModuleInlineAsm( ModuleHandle, asm, string.IsNullOrEmpty( asm ) ? 0 : asm.Length );
         }
 
-        /// <inheritdoc/>
+        /// <summary>Disposes the <see cref="BitcodeModule"/>, releasing resources associated with the module in native code</summary>
         public void Dispose( )
         {
-            // if not already disposed, dispose the module
-            // Do this only on dispose. The containing context
-            // will clean up the module when it is disposed or
-            // finalized. Since finalization order isn't
-            // deterministic it is possible that the module is
-            // finalized after the context has already run its
-            // finalizer, which would cause an access violation
-            // in the native LLVM layer.
+            // if not already disposed, dispose the module. Do this only on dispose. The containing context
+            // will clean up the module when it is disposed or finalized. Since finalization order isn't
+            // deterministic it is possible that the module is finalized after the context has already run its
+            // finalizer, which would cause an access violation in the native LLVM layer.
             if( !IsDisposed )
             {
                 // remove the module handle from the module cache.

src/Ubiquity.NET.Llvm/ComdatCollection.cs

@@ -70,10 +70,12 @@ public void Clear( )
         /// <returns><see langword="true"/> if the entry is present and <see langword="false"/> if not</returns>
         public bool Contains( string key ) => InternalComdatMap.ContainsKey( key );
 
-        /// <inheritdoc/>
+        /// <summary>Gets an enumerator for all the <see cref="Comdat"/>s in the collection</summary>
+        /// <returns>Enumerator</returns>
         public IEnumerator<Comdat> GetEnumerator( ) => InternalComdatMap.Values.GetEnumerator( );
 
-        /// <inheritdoc/>
+        /// <summary>Gets an enumerator for all the <see cref="Comdat"/>s in the collection</summary>
+        /// <returns>Enumerator</returns>
         IEnumerator IEnumerable.GetEnumerator( ) => InternalComdatMap.Values.GetEnumerator( );
 
         /// <summary>Removes a <see cref="Comdat"/> entry from the module</summary>

src/Ubiquity.NET.Llvm/Context.cs

@@ -855,7 +855,12 @@ internal Context( LLVMContextRef contextRef )
             LLVMContextSetDiagnosticHandler( ContextHandle, ActiveHandler, IntPtr.Zero );
         }
 
-        /// <inheritdoc />
+        /// <summary>Disposes the context to release unmanaged resources deterministically</summary>
+        /// <param name="disposing">Indicates whether this is from a call to Dispose (<see langword="true"/>) or if from a finalizer</param>
+        /// <remarks>
+        /// If <paramref name="disposing"/> is <see langword="true"/> then this will release managed and unmanaged resources.
+        /// Otherwise, this will only release the native/unmanaged resources.
+        /// </remarks>
         protected override void Dispose( bool disposing )
         {
             // disconnect all modules so that any future critical finalization has no impact

src/Ubiquity.NET.Llvm/ContextCache.cs

@@ -9,7 +9,6 @@
 using System.Collections.Generic;
 using System.Threading;
 
-using Ubiquity.ArgValidators;
 using Ubiquity.NET.Llvm.Interop;
 
 namespace Ubiquity.NET.Llvm

src/Ubiquity.NET.Llvm/DataLayout.cs

@@ -6,7 +6,6 @@
 
 using System;
 using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
 
 using Ubiquity.ArgValidators;
 using Ubiquity.NET.Llvm.Interop;
@@ -200,7 +199,6 @@ public uint PreferredAlignmentOf( Value value )
         /// <param name="structType">Type of the structure</param>
         /// <param name="offset">Offset to determine the index of</param>
         /// <returns>Index of the element</returns>
-        [SuppressMessage( "Microsoft.Design", "CA1011:ConsiderPassingBaseTypesAsParameters", Justification = "Specific type required by interop call" )]
         public uint ElementAtOffset( IStructType structType, ulong offset )
         {
             VerifySized( structType, nameof( structType ) );
@@ -211,14 +209,15 @@ public uint ElementAtOffset( IStructType structType, ulong offset )
         /// <param name="structType">Type of the structure</param>
         /// <param name="element">index of the element in the structure</param>
         /// <returns>Offset of the element from the beginning of the structure</returns>
-        [SuppressMessage( "Microsoft.Design", "CA1011:ConsiderPassingBaseTypesAsParameters", Justification = "Specific type required by interop call" )]
         public ulong OffsetOfElement( IStructType structType, uint element )
         {
             VerifySized( structType, nameof( structType ) );
             return LLVMOffsetOfElement( DataLayoutHandle, structType.GetTypeRef( ), element );
         }
 
-        /// <inheritdoc/>
+        /// <summary>Converts the layout to a string representation of the layout data</summary>
+        /// <returns>Data layout as a string</returns>
+        /// <seealso href="xref:llvm_langref#data-layout">DICompositeType</seealso>
         public override string ToString( ) => LLVMCopyStringRepOfTargetData( DataLayoutHandle );
 
         /// <summary>Gets the byte size of a type</summary>
@@ -265,7 +264,6 @@ internal static DataLayout FromHandle( LLVMTargetDataRef targetDataRef )
 
         internal LLVMTargetDataRef DataLayoutHandle { get; }
 
-        // ReSharper disable once ParameterOnlyUsedForPreconditionCheck.Local
         private static void VerifySized( [ValidatedNotNull] ITypeRef type, string name )
         {
             if( type == null )

src/Ubiquity.NET.Llvm/DebugInfo/DIScope.cs

@@ -4,8 +4,6 @@
 // </copyright>
 // -----------------------------------------------------------------------
 
-using System;
-
 using Ubiquity.NET.Llvm.Interop;
 
 using static Ubiquity.NET.Llvm.Interop.NativeMethods;

src/Ubiquity.NET.Llvm/DebugInfo/TupleTypedArrayWrapper.cs

@@ -4,14 +4,12 @@
 // </copyright>
 // -----------------------------------------------------------------------
 
-using System;
 using System.Collections;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Linq;
 
 using Ubiquity.ArgValidators;
-using Ubiquity.NET.Llvm.Properties;
 
 namespace Ubiquity.NET.Llvm.DebugInfo
 {
@@ -30,10 +28,12 @@ public class TupleTypedArrayWrapper<T>
         /// <summary>Gets the underlying tuple for this wrapper</summary>
         public MDTuple? Tuple { get; }
 
-        /// <inheritdoc />
+        /// <summary>Gets the count of operands in the <see cref="MDTuple"/></summary>
         public int Count => Tuple?.Operands.Count ?? 0;
 
-        /// <inheritdoc />
+        /// <summary>Gets an item from the tuple</summary>
+        /// <param name="index">Index of the item to retrieve</param>
+        /// <returns>The element at <paramref name="index"/> in the tuple</returns>
         public T? this[ int index ]
         {
             get
@@ -43,7 +43,9 @@ public T? this[ int index ]
             }
         }
 
-        /// <inheritdoc />
+        /// <summary>Gets an enumerator for the items in the <see cref="MDTuple"/></summary>
+        /// <returns>Enumerator</returns>
+        /// <remarks>If the underlying tuple is empty this is an empty enumeration</remarks>
         public IEnumerator<T?> GetEnumerator( )
         {
             return Tuple is null
@@ -53,7 +55,9 @@ public T? this[ int index ]
                         .GetEnumerator( );
         }
 
-        /// <inheritdoc />
+        /// <summary>Gets an enumerator for the items in the <see cref="MDTuple"/></summary>
+        /// <returns>Enumerator</returns>
+        /// <remarks>If the underlying tuple is empty this is an empty enumeration</remarks>
         IEnumerator IEnumerable.GetEnumerator( ) => GetEnumerator( );
 
         internal TupleTypedArrayWrapper( MDTuple? tuple )

src/Ubiquity.NET.Llvm/Instructions/CatchReturn.cs

@@ -4,8 +4,6 @@
 // </copyright>
 // -----------------------------------------------------------------------
 
-using System.Collections.Generic;
-
 using Ubiquity.NET.Llvm.Interop;
 using Ubiquity.NET.Llvm.Values;
 

src/Ubiquity.NET.Llvm/Instructions/FuncletPad.cs

@@ -4,8 +4,6 @@
 // </copyright>
 // -----------------------------------------------------------------------
 
-using System.Collections.Generic;
-
 using Ubiquity.NET.Llvm.Interop;
 using Ubiquity.NET.Llvm.Values;
 

src/Ubiquity.NET.Llvm/Instructions/Invoke.cs

@@ -4,7 +4,6 @@
 // </copyright>
 // -----------------------------------------------------------------------
 
-using System;
 using System.Collections.Generic;
 using System.Linq;
 

src/Ubiquity.NET.Llvm/Instructions/SuccessorBlockCollection.cs

@@ -4,7 +4,6 @@
 // </copyright>
 // -----------------------------------------------------------------------
 
-using System;
 using System.Collections;
 using System.Collections.Generic;
 using System.Linq;
@@ -41,10 +40,11 @@ public BasicBlock this[ int index ]
             }
         }
 
-        /// <inheritdoc/>
+        /// <summary>Gets the count of elements in this collection</summary>
         public int Count => checked((int)LLVMGetNumSuccessors( Container.ValueHandle ));
 
-        /// <inheritdoc/>
+        /// <summary>Gets an enumerator for the <see cref="BasicBlock"/>s in this collection</summary>
+        /// <returns>Enumerator for the collection</returns>
         public IEnumerator<BasicBlock> GetEnumerator( )
         {
             for( int i = 0; i < Count; ++i )
@@ -53,7 +53,8 @@ public IEnumerator<BasicBlock> GetEnumerator( )
             }
         }
 
-        /// <inheritdoc/>
+        /// <summary>Gets an enumerator for the <see cref="BasicBlock"/>s in this collection</summary>
+        /// <returns>Enumerator for the collection</returns>
         IEnumerator IEnumerable.GetEnumerator( ) => GetEnumerator( );
 
         /// <inheritdoc/>

src/Ubiquity.NET.Llvm/JIT/OrcJit.cs

@@ -250,7 +250,8 @@ UInt64 CompileAction( LLVMOrcJITStackRef jitStackHandle, IntPtr ctx )
         }
 #endif
 
-        /// <inheritdoc/>
+        /// <summary>Releases unmanaged resources for this instance</summary>
+        /// <param name="disposing">Indicates if this is from a Dispose (<see langword="true"/>) or a finalizer</param>
         protected override void Dispose( bool disposing )
         {
             JitStackHandle?.Dispose( );

src/Ubiquity.NET.Llvm/Metadata/LlvmMetadata.cs

@@ -134,7 +134,8 @@ public virtual void ReplaceAllUsesWith( LlvmMetadata other )
             MetadataHandle = default;
         }
 
-        /// <inheritdoc/>
+        /// <summary>Formats the metadata as a string</summary>
+        /// <returns>Metadata as a string</returns>
         public override string ToString( )
         {
             return MetadataHandle == default ? string.Empty : LibLLVMMetadataAsString( MetadataHandle );

src/Ubiquity.NET.Llvm/Metadata/MetadataOperandCollection.cs

@@ -35,10 +35,11 @@ public LlvmMetadata? this[ int index ]
             }
         }
 
-        /// <inheritdoc/>
+        /// <summary>Gets the count of operands in this collection</summary>
         public int Count => checked(( int )LibLLVMMDNodeGetNumOperands( Container.MetadataHandle ));
 
-        /// <inheritdoc/>
+        /// <summary>Gets an enumerator for the operands in this collection</summary>
+        /// <returns>Enumerator of operands</returns>
         public IEnumerator<LlvmMetadata?> GetEnumerator( )
         {
             for( int i = 0; i < Count; ++i )
@@ -47,7 +48,8 @@ public LlvmMetadata? this[ int index ]
             }
         }
 
-        /// <inheritdoc/>
+        /// <summary>Gets an enumerator for the operands in this collection</summary>
+        /// <returns>Enumerator of operands</returns>
         IEnumerator IEnumerable.GetEnumerator( ) => GetEnumerator( );
 
         /// <inheritdoc/>

src/Ubiquity.NET.Llvm/ObjectFile/Relocation.cs

@@ -37,10 +37,13 @@ public struct Relocation
         /// <summary>Gets the <see cref="Ubiquity.NET.Llvm.ObjectFile.Section"/> this relocation belongs to</summary>
         public Section Section { get; }
 
-        /// <inheritdoc/>
+        /// <summary>Performs equality checks against an <see cref="object"/></summary>
+        /// <param name="obj">object to test for equality with this instance</param>
+        /// <returns><see langword="true"/> if <paramref name="obj"/> is equal to this instance</returns>
         public override bool Equals( object obj ) => ( obj is Relocation other ) && Equals( other );
 
-        /// <inheritdoc/>
+        /// <summary>Gets a hash code for this <see cref="Relocation"/></summary>
+        /// <returns>Hash code</returns>
         public override int GetHashCode( ) => IteratorRef.GetHashCode( );
 
         /// <summary>Equality comparison</summary>
@@ -55,7 +58,9 @@ public struct Relocation
         /// <returns>Result of inequality test</returns>
         public static bool operator !=( Relocation left, Relocation right ) => !( left == right );
 
-        /// <inheritdoc/>
+        /// <summary>Performs equality checks against another <see cref="Relocation"/></summary>
+        /// <param name="other">object to test for equality with this instance</param>
+        /// <returns><see langword="true"/> if <paramref name="other"/> is equal to this instance</returns>
         public bool Equals( Relocation other ) => IteratorRef.Equals( other.IteratorRef );
 
         internal Relocation( Section owningSection, LLVMRelocationIteratorRef iterator )

src/Ubiquity.NET.Llvm/ObjectFile/Section.cs

@@ -67,10 +67,13 @@ public void MoveToContainingSection( Symbol symbol )
         /// <summary>Gets the address of the section</summary>
         public ulong Address => LLVMGetSectionAddress( IteratorRef );
 
-        /// <inheritdoc/>
+        /// <summary>Tests an <see cref="object"/> for equality</summary>
+        /// <param name="obj"><see cref="object"/> to compare with this instance</param>
+        /// <returns><see langword="true"/> if the </returns>
         public override bool Equals( object obj ) => ( obj is Section other ) && Equals( other );
 
-        /// <inheritdoc/>
+        /// <summary>Gets a hash code for this <see cref="Section"/></summary>
+        /// <returns>Hash code</returns>
         public override int GetHashCode( ) => IteratorRef.GetHashCode( );
 
         /// <summary>Equality comparison</summary>
@@ -85,7 +88,9 @@ public void MoveToContainingSection( Symbol symbol )
         /// <returns>Result of inequality test</returns>
         public static bool operator !=( Section left, Section right ) => !( left == right );
 
-        /// <inheritdoc/>
+        /// <summary>Tests an <see cref="Section"/> for equality</summary>
+        /// <param name="other"><see cref="Section"/> to compare with this instance</param>
+        /// <returns><see langword="true"/> if the </returns>
         public bool Equals( Section other ) => IteratorRef.Equals( other.IteratorRef );
 
         internal Section( TargetBinary objFile, LLVMSectionIteratorRef iterator )