Reinstate remarks that were never ported to dotnet/docs (#9755)

Author: gewarren

xml/System.ComponentModel.Composition.Hosting/AssemblyCatalog.xml

@@ -496,7 +496,14 @@ The assembly referenced by `codeBase` is loaded into the Load context.
         <param name="definition">Conditions that specify which exports to match.</param>
         <summary>Gets a collection of exports that match the conditions specified by the import definition.</summary>
         <returns>A collection of exports that match the conditions specified by <paramref name="definition" />.</returns>
-        <remarks>For more information about this API, see &lt;see href="/dotnet/fundamentals/runtime-libraries/system-componentmodel-composition-hosting-assemblycatalog-getexports"&gt;Supplemental API remarks for System.ComponentModel.Composition.Hosting.AssemblyCatalog.GetExports&lt;/see&gt;.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+## Notes to inheritors
+
+Overriders of this property should never return `null` if no <xref:System.ComponentModel.Composition.Primitives.ExportDefinition> matches the conditions defined by `definition`; instead, return an empty <xref:System.Collections.Generic.IEnumerable%601>.
+
+]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="definition" /> is <see langword="null" />.</exception>
         <exception cref="T:System.ObjectDisposedException">The <see cref="T:System.ComponentModel.Composition.Primitives.ComposablePartCatalog" /> has been disposed.</exception>

xml/System.ComponentModel.Composition.Hosting/CompositionScopeDefinition.xml

@@ -306,13 +306,17 @@ For more information, see [Implementing a Dispose method](/dotnet/standard/garba
         <param name="definition">Conditions that specify which exports to match.</param>
         <summary>Gets a collection of exports that match the conditions specified by the import definition.</summary>
         <returns>A collection of exports that match the specified conditions.</returns>
-        <remarks>For more information about this API, see &lt;see href="/dotnet/fundamentals/runtime-libraries/system-componentmodel-composition-hosting-compositionscopedefinition-getexports"&gt;Supplemental API remarks for System.ComponentModel.Composition.Hosting.CompositionScopeDefinition.GetExports&lt;/see&gt;.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+## Note to inheritors
+
+Overriders of this property should never return `null`. If there is no <xref:System.ComponentModel.Composition.Primitives.ExportDefinition> that matches the conditions defined by `definition`, return an empty <xref:System.Collections.Generic.IEnumerable%601>.
+
+]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentNullException">
-          <paramref name="definition" /> is <see langword="null" />.
-            </exception>
-        <exception cref="T:System.ObjectDisposedException">
-            The <see cref="T:System.ComponentModel.Composition.Primitives.ComposablePartCatalog" /> has been disposed.
-            </exception>
+          <paramref name="definition" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.ObjectDisposedException">The <see cref="T:System.ComponentModel.Composition.Primitives.ComposablePartCatalog" /> has been disposed.</exception>
       </Docs>
     </Member>
     <Member MemberName="OnChanged">

xml/System.ComponentModel.Composition.Hosting/FilteredCatalog.xml

@@ -246,13 +246,17 @@
         <param name="definition">The import to match.</param>
         <summary>Gets the exported parts from this catalog that match the specified import.</summary>
         <returns>A collection of matching parts.</returns>
-        <remarks>For more information about this API, see &lt;see href="/dotnet/fundamentals/runtime-libraries/system-componentmodel-composition-hosting-filteredcatalog-getexports"&gt;Supplemental API remarks for System.ComponentModel.Composition.Hosting.FilteredCatalog.GetExports&lt;/see&gt;.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+## Notes to inheritors
+
+Overriders of this property should never return `null` if no <xref:System.ComponentModel.Composition.Primitives.ExportDefinition> matches the conditions defined by `definition`; instead, return an empty <xref:System.Collections.Generic.IEnumerable%601>.
+
+]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentNullException">
-          <paramref name="definition" /> is <see langword="null" />.
-            </exception>
-        <exception cref="T:System.ObjectDisposedException">
-            The <see cref="T:System.ComponentModel.Composition.Primitives.ComposablePartCatalog" /> has been disposed.
-            </exception>
+          <paramref name="definition" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.ObjectDisposedException">The <see cref="T:System.ComponentModel.Composition.Primitives.ComposablePartCatalog" /> has been disposed.</exception>
       </Docs>
     </Member>
     <MemberGroup MemberName="IncludeDependencies">

xml/System.ComponentModel.Composition.Primitives/ContractBasedImportDefinition.xml

@@ -57,7 +57,16 @@
       <Parameters />
       <Docs>
         <summary>Initializes a new instance of the <see cref="T:System.ComponentModel.Composition.Primitives.ContractBasedImportDefinition" /> class.</summary>
-        <remarks>For more information about this API, see &lt;see href="/dotnet/fundamentals/runtime-libraries/system-componentmodel-composition-primitives-contractbasedimportdefinition--ctor"&gt;Supplemental API remarks for System.ComponentModel.Composition.Primitives.ContractBasedImportDefinition..ctor&lt;/see&gt;.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Note to inheritors
+
+Derived types calling this constructor can optionally override the <xref:System.ComponentModel.Composition.Primitives.ImportDefinition.ContractName>, <xref:System.ComponentModel.Composition.Primitives.ContractBasedImportDefinition.RequiredTypeIdentity>,
+<xref:System.ComponentModel.Composition.Primitives.ContractBasedImportDefinition.RequiredMetadata>, <xref:System.ComponentModel.Composition.Primitives.ImportDefinition.Cardinality>, <xref:System.ComponentModel.Composition.Primitives.ImportDefinition.IsPrerequisite>, <xref:System.ComponentModel.Composition.Primitives.ImportDefinition.IsRecomposable>, and <xref:System.ComponentModel.Composition.Primitives.ContractBasedImportDefinition.RequiredCreationPolicy> properties.
+
+]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName=".ctor">

xml/System.ComponentModel.Composition.Primitives/Export.xml

@@ -256,11 +256,17 @@
       <Docs>
         <summary>Returns the exported object the export provides.</summary>
         <returns>The exported object the export provides.</returns>
-        <remarks>For more information about this API, see &lt;see href="/dotnet/fundamentals/runtime-libraries/system-componentmodel-composition-primitives-export-getexportedvaluecore"&gt;Supplemental API remarks for System.ComponentModel.Composition.Primitives.Export.GetExportedValueCore&lt;/see&gt;.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+## Note to inheritors
+
+Overrides of this method should never return `null`.
+
+]]></format>
+        </remarks>
         <exception cref="T:System.NotImplementedException">The <see cref="M:System.ComponentModel.Composition.Primitives.Export.GetExportedValueCore" /> method was not overridden by a derived class.</exception>
         <exception cref="T:System.ComponentModel.Composition.CompositionException">An error occurred during composition. <see cref="P:System.ComponentModel.Composition.CompositionException.Errors" /> will contain a collection of errors that occurred.</exception>
-        <exception cref="T:System.ComponentModel.Composition.CompositionContractMismatchException">The current instance is an instance of <see cref="T:System.Lazy`1" />, and the underlying exported value cannot be cast to <c>T</c>.
-            </exception>
+        <exception cref="T:System.ComponentModel.Composition.CompositionContractMismatchException">The current instance is an instance of <see cref="T:System.Lazy`1" />, and the underlying exported value cannot be cast to <c>T</c>.</exception>
       </Docs>
     </Member>
     <Member MemberName="Metadata">

xml/System.ComponentModel.Composition.Primitives/ImportDefinition.xml

@@ -276,10 +276,16 @@
         <summary>Gets a value that indicates whether the export represented by the specified definition satisfies the constraints of this import definition.</summary>
         <returns>
           <see langword="true" /> if the constraints are satisfied; otherwise, <see langword="false" />.</returns>
-        <remarks>For more information about this API, see &lt;see href="/dotnet/fundamentals/runtime-libraries/system-componentmodel-composition-primitives-importdefinition-isconstraintsatisfiedby"&gt;Supplemental API remarks for System.ComponentModel.Composition.Primitives.ImportDefinition.IsConstraintSatisfiedBy&lt;/see&gt;.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+## Note to inheritors
+
+Overrides of this method can provide a more optimized execution of the <xref:System.ComponentModel.Composition.Primitives.ImportDefinition.Constraint> property, but the result should remain consistent.
+
+]]></format>
+        </remarks>
         <exception cref="T:System.ArgumentNullException">
-          <paramref name="exportDefinition" /> is <see langword="null" />.
-            </exception>
+          <paramref name="exportDefinition" /> is <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName="IsPrerequisite">

xml/System.ComponentModel.DataAnnotations/ValidationAttribute.xml

@@ -93,7 +93,12 @@
       <Parameters />
       <Docs>
         <summary>Initializes a new instance of the <see cref="T:System.ComponentModel.DataAnnotations.ValidationAttribute" /> class.</summary>
-        <remarks>For more information about this API, see &lt;see href="/dotnet/fundamentals/runtime-libraries/system-componentmodel-dataannotations-validationattribute--ctor"&gt;Supplemental API remarks for System.ComponentModel.DataAnnotations.ValidationAttribute..ctor&lt;/see&gt;.</remarks>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+This constructor chooses a generic validation error message. If you subclass `ValidationAttribute`, use other constructors or supply a better message.
+
+]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName=".ctor">
@@ -138,8 +143,7 @@
         <remarks>
           <format type="text/markdown"><![CDATA[
 
-## Remarks
- This constructor provides a resource accessor function that is used by the <xref:System.ComponentModel.DataAnnotations.ValidationAttribute.ErrorMessageString%2A> property to retrieve an error message.
+This constructor provides a resource accessor function that is used by the <xref:System.ComponentModel.DataAnnotations.ValidationAttribute.ErrorMessageString%2A> property to retrieve an error message.
 
  ]]></format>
         </remarks>
@@ -232,8 +236,7 @@
         <remarks>
           <format type="text/markdown"><![CDATA[
 
-## Remarks
- This property is the error message that you associate with the validation control. It is used for non-localized error messages.
+This property is the error message that you associate with the validation control. It is used for non-localized error messages.
 
  ]]></format>
         </remarks>