Document System.Reflection.MetadataAssemblyResolver and PathAssemblyResolver (#2871)

* Document System.Reflection.MetadataAssemblyResolver and PathAssemblyResolver

* suggestions by rpetrusha

Co-Authored-By: Ron Petrusha <[email protected]>

* suggestion by rpetrusha

Co-Authored-By: Ron Petrusha <[email protected]>

* reference for "it"

* clarify public key token

* Fixed broken xref.

Author: carlossanlop

xml/System.Reflection/MetadataAssemblyResolver.xml

@@ -14,7 +14,7 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Provides the base class for binding algorithms used by <see cref="T:System.Reflection.MetadataLoadContext"/>.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -31,7 +31,7 @@
       </AssemblyInfo>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Initializes an instance of <see cref="T:System.Reflection.MetadataAssemblyResolver" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -54,12 +54,31 @@
         <Parameter Name="assemblyName" Type="System.Reflection.AssemblyName" />
       </Parameters>
       <Docs>
-        <param name="context">To be added.</param>
-        <param name="assemblyName">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="context">The metadata load context object that represents the closed universe of <see cref="T:System.Type" /> objects loaded for inspection-only purposes.</param>
+        <param name="assemblyName">The name of the assembly.</param>
+        <summary>Returns an assembly from a given assembly name.</summary>
+        <returns>The assembly for the provided <paramref name="assemblyName" />.</returns>
+        <remarks>
+          <format type="text/markdown">
+  <![CDATA[
+
+## Remarks
+
+Binding an assembly name to an assembly occurs when <xref:System.Reflection.MetadataLoadContext.LoadFromAssemblyName%2A> is called or when a type from one assembly has a dependency on another assembly. The handler that overrides `Resolve` should use <xref:System.Reflection.MetadataLoadContext.LoadFromStream%2A?displayProperty=nameWithType>, <xref:System.Reflection.MetadataLoadContext.LoadFromAssemblyPath%2A?displayProperty=nameWithType> or <xref:System.Reflection.MetadataLoadContext.LoadFromByteArray%2A?displayProperty=nameWithType> to load the requested assembly and return it.
+
+To indicate the failure to find an assembly, the handler should return `null` rather than throwing an exception. Returning `null` commits the failure so that future attempts to load that name will fail without re-invoking the handler.
+
+If the handler throws an exception, the exception will be passed through to the application that invoked the operation that triggered the binding. The <xref:System.Reflection.MetadataLoadContext> will not catch it, and no binding will occur.
+
+The handler will generally not be called more than once for the same name, unless two threads race to load the same assembly. Even in that case, one result will win and be atomically bound to the name.
+
+The <xref:System.Reflection.MetadataLoadContext> intentionally performs no ref-def matching on the returned assembly as what constitutes a ref-def match is a policy. It is also the kind of arbitrary restriction that <xref:System.Reflection.MetadataLoadContext> strives to avoid.
+
+The <xref:System.Reflection.MetadataLoadContext> cannot consume assemblies from other metadata load contexts or other type providers (such as the underlying runtime's own reflection system). If a handler returns such an assembly, the <xref:System.Reflection.MetadataLoadContext> throws a <xref:System.IO.FileLoadException>.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.Reflection/PathAssemblyResolver.xml

@@ -14,8 +14,24 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
-    <remarks>To be added.</remarks>
+    <summary>Represents a metadata assembly resolver that uses paths to every assembly that may be loaded.</summary>
+    <remarks>
+      <format type="text/markdown">
+  <![CDATA[
+
+## Remarks
+
+The file name is expected to be the same as the assembly's simple name. Multiple assemblies can exist on disk with the same name but in different directories. A single instance of `PathAssemblyResolver` can be used with multiple <xref:System.Reflection.MetadataAssemblyResolver> instances.
+
+In order for an <xref:System.Reflection.AssemblyName> to match a loaded assembly, <xref:System.Reflection.AssemblyName.Name?displayProperty=nameWithType> must be equal (casing ignored).
+
+* If a public key token is specified for the <xref:System.Reflection.AssemblyName>, it must be equal.
+* If a public key token is not specified for <xref:System.Reflection.AssemblyName>, assemblies with no public key token are selected over those with a public key token.
+* If more than one assembly matches, the assembly with the highest <xref:System.Reflection.AssemblyName.Version?displayProperty=nameWithType> is returned.
+* <xref:System.Reflection.AssemblyName.CultureName?displayProperty=nameWithType> is ignored.
+
+      ]]></format>
+    </remarks>
   </Docs>
   <Members>
     <Member MemberName=".ctor">
@@ -34,9 +50,11 @@
         <Parameter Name="assemblyPaths" Type="System.Collections.Generic.IEnumerable&lt;System.String&gt;" />
       </Parameters>
       <Docs>
-        <param name="assemblyPaths">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="assemblyPaths">A collection of assembly path strings.</param>
+        <summary>Initializes a new instance of the <see cref="System.Reflection.PathAssemblyResolver"/> class.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException"><paramref name="assemblyPaths" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.ArgumentException">One of the paths in <paramref name="assemblyPaths" /> is invalid.</exception>
       </Docs>
     </Member>
     <Member MemberName="Resolve">
@@ -58,12 +76,20 @@
         <Parameter Name="assemblyName" Type="System.Reflection.AssemblyName" />
       </Parameters>
       <Docs>
-        <param name="context">To be added.</param>
-        <param name="assemblyName">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="context">The metadata load context object that represents the closed universe of <see cref="System.Type" /> objects loaded for inspection-only purposes.</param>
+        <param name="assemblyName">The name of the assembly.</param>
+        <summary>Returns an assembly from a given assembly name.</summary>
+        <returns>The assembly for the provided <paramref name="assemblyName" />.</returns>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+See the <xref:System.Reflection.MetadataAssemblyResolver> remarks for more information.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>