Fix link in Remarks sections (#3728)

* fix links in remarks

* fix more links in remarks

* review on staging

* fix warning and review on staging

* Apply suggestions from Scott

Co-Authored-By: Scott Addie <[email protected]>

Author: gewarren

xml/System.Collections.Immutable/ImmutableSortedSet`1.xml

@@ -49,11 +49,11 @@ Instances of this class are not required to be safe for concurrent access by mul
       <Docs>
         <summary>Initializes a new instance of the <see cref="T:System.Composition.Hosting.Core.ExportDescriptorProvider" /> class.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- This is a protected constructor that can only be called from derived classes.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+ This is a protected constructor that can only be called from derived classes.
+
  ]]></format>
         </remarks>
       </Docs>
@@ -87,11 +87,12 @@ Instances of this class are not required to be safe for concurrent access by mul
         <summary>Retrieves promise export descriptors for the specified export key.</summary>
         <returns>A collection of promises for new export descriptors.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
-  
-## Remarks  
- A provider will only be queried once for each unique export key. The descriptor accessor can only be queried immediately if the descriptor being promised is an adapter, such as <see cref="Lazy{T}"/>; otherwise, dependencies should only be queried within execution of the function provided to the <xref:System.Composition.Hosting.Core.ExportDescriptorPromise>. The actual descriptors provided by this method, must not close over or reference any aspect of the dependency/promise structure, as this would prevent the structure from being garbage collected.  
-  
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+A provider is only queried once for each unique export key. The descriptor accessor can only be queried immediately if the descriptor being promised is an adapter, such as <xref:System.Lazy%601>. Otherwise, dependencies should only be queried within execution of the function provided to the <xref:System.Composition.Hosting.Core.ExportDescriptorPromise>. The actual descriptors provided by this method must not close over or reference any aspect of the dependency/promise structure, as this would prevent the structure from being garbage collected.
+
  ]]></format>
         </remarks>
       </Docs>

xml/System.Composition.Hosting.Core/ExportDescriptorProvider.xml

@@ -61,7 +61,7 @@ No `Activity` methods allow exceptions to escape as a response to bad inputs. Th
         <param name="operationName">The name of the operation.</param>
         <summary>Initializes a new instance of the <see cref="T:System.Diagnostics.Activity" /> class.</summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
@@ -123,11 +123,11 @@ Note that <xref:System.Diagnostics.Activity> has a "builder" pattern: you call t
         <returns>
           <see langword="this" /> for convenient chaining.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-This key/value pair is included in the collection returned by the <see cref="P:System.Diagnostics.Activity.Baggage" /> property, and can also be retrieved by the <xref:System.Diagnostics.Activity.GetBaggageItem%2A> method. 
+This key/value pair is included in the collection returned by the <xref:System.Diagnostics.Activity.Baggage> property, and can also be retrieved by the <xref:System.Diagnostics.Activity.GetBaggageItem%2A> method.
 
 `Baggage` is meant for information that is needed for runtime control. For information that is useful to show up in the log with the <xref:System.Diagnostics.Activity>, use the <xref:System.Diagnostics.Activity.Tags> property.
 
@@ -169,9 +169,9 @@ This key/value pair is included in the collection returned by the <see cref="P:S
 
 ## Remarks
 
-This key/value pair is included in the collection returned by the <see cref="P:System.Diagnostics.Activity.Tags" /> property.
+This key/value pair is included in the collection returned by the <xref:System.Diagnostics.Activity.Tags> property.
 
-<xref:System.Diagnostics.Activity.Tags> is meant for information that is useful to log with the <xref:System.Diagnostics.Activity>. For information that is needed for runtime control, use the <xref:System.Diagnostics.Activity.Baggage> property.
+<xref:System.Diagnostics.Activity.Tags> is meant for information that is useful to log with the <xref:System.Diagnostics.Activity>. For information that's needed for runtime control, use the <xref:System.Diagnostics.Activity.Baggage> property.
 
 ]]></format>
         </remarks>
@@ -200,7 +200,7 @@ This key/value pair is included in the collection returned by the <see cref="P:S
         <summary>Gets a collection of key/value pairs that represents information that is passed to children of this <see cref="T:System.Diagnostics.Activity" />.</summary>
         <value>An enumeration of string-string key-value pairs.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
@@ -259,7 +259,7 @@ This key/value pair is included in the collection returned by the <see cref="P:S
         <summary>Gets or sets the default ID format for the <see cref="T:System.Diagnostics.Activity" />.</summary>
         <value>To be added.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 The `Activity` instance tries to use the same format for IDs as its parent. If the activity has no parent, this property determines the default format to use.
 
@@ -313,7 +313,7 @@ The `Activity` instance tries to use the same format for IDs as its parent. If t
         <value>
           <see langword="true" /> to always use the <see cref="P:System.Diagnostics.Activity.DefaultIdFormat" />; otherwise, <see langword="false" />.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 Normally if the <xref:System.Diagnostics.Activity.ParentId> is defined, its format determines the format used by the current <xref:System.Diagnostics.Activity>. However, if `ForceDefaultFormat` is set to `true`, the ID format is always defined by the <xref:System.Diagnostics.Activity.DefaultIdFormat> property even if the <xref:System.Diagnostics.Activity.ParentId> is defined and the parent has a different format.
 
@@ -373,7 +373,7 @@ Normally if the <xref:System.Diagnostics.Activity.ParentId> is defined, its form
         <summary>Gets an identifier that is specific to a particular request.</summary>
         <value>The activity ID.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
@@ -428,7 +428,7 @@ An ID has a hierarchical structure: `root-id.id1_id2.id3_`. The ID is generated
         <summary>Gets the operation name.</summary>
         <value>The name of the operation.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
@@ -486,13 +486,13 @@ An operation name is the *coarsest* name that is useful for grouping/filtering.
         <summary>Gets the ID of this activity's parent.</summary>
         <value>The parent ID, if one exists, or <see langword="null" /> if it does not.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-If the parent for this <xref:System.Diagnostics.Activity> comes from outside the process, the <xref:System.Diagnostics.Activity> does not have a parent but *may* have a parent ID (which was deserialized from the parent).  
+If the parent for this <xref:System.Diagnostics.Activity> comes from outside the process, the <xref:System.Diagnostics.Activity> does not have a parent but *may* have a parent ID (which was deserialized from the parent).
 
-This property value can be `null` if this is a root <see cref="T:System.Diagnostics.Activity" /> (i.e. it has no <xref:System.Diagnostics.Activity.Parent>).  See [Id Format](href="https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md#id-format") for more details.
+This property value can be `null` if this is a root <xref:System.Diagnostics.Activity> (that is, it has no <xref:System.Diagnostics.Activity.Parent>). For more information, see [ID format](href="https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md#id-format").
 
 ]]></format>
         </remarks>
@@ -518,7 +518,7 @@ This property value can be `null` if this is a root <see cref="T:System.Diagnost
         <summary>Gets the parent's <see cref="P:System.Diagnostics.Activity.SpanId" />.</summary>
         <value>The parent's <see cref="P:System.Diagnostics.Activity.SpanId" />.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 If the <xref:System.Diagnostics.Activity.ParentId?displayProperty=nameWithType> is in the W3C format, this property returns the <xref:System.Diagnostics.Activity.SpanId> part of the ParentId.  Otherwise it returns a zero <xref:System.Diagnostics.Activity.SpanId>.
 
@@ -572,7 +572,7 @@ If the <xref:System.Diagnostics.Activity.ParentId?displayProperty=nameWithType>
         <summary>Gets the root ID of this <see cref="T:System.Diagnostics.Activity" />.</summary>
         <value>The root ID, or <see langword="null" /> if the current instance has either a <see cref="P:System.Diagnostics.Activity.ParentId" /> or an <see cref="P:System.Diagnostics.Activity.Id" />.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
@@ -637,7 +637,7 @@ The root ID is a substring from the <xref:System.Diagnostics.Activity.Id> or the
         <returns>
           <see langword="this" /> for convenient chaining.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
@@ -675,11 +675,11 @@ The specified format will take precedence over `Parent.IdFormat`, the <xref:Syst
         <returns>
           <see langword="this" /> for convenient chaining.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
-This property should only be used in 'boundary' scenarios where an <see cref="T:System.Diagnostics.Activity" /> from another process logically started this <see cref="T:System.Diagnostics.Activity" />. The `parentId` brings up the <xref:System.Diagnostics.Activity.Tags> (as well as the <xref:System.Diagnostics.Activity.ParentId> property) and can be used to reconstruct the causal tree.
+This property should only be used in 'boundary' scenarios where an <xref:System.Diagnostics.Activity> from another process logically started this <xref:System.Diagnostics.Activity>. The `parentId` brings up the <xref:System.Diagnostics.Activity.Tags> (as well as the <xref:System.Diagnostics.Activity.ParentId> property) and can be used to reconstruct the causal tree.
 
 ]]></format>
         </remarks>
@@ -712,7 +712,7 @@ This property should only be used in 'boundary' scenarios where an <see cref="T:
         <returns>
           <see langword="this" /> for convenient chaining.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
@@ -799,7 +799,7 @@ This method has the advantage that no string manipulation is needed to set the I
         <returns>
           <see langword="this" /> for convenient chaining.</returns>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
@@ -838,7 +838,7 @@ Use <xref:System.Diagnostics.DiagnosticSource.StartActivity%2A?displayProperty=n
         <summary>Gets the time when the operation started.</summary>
         <value>The UTC time that the operation started.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
@@ -954,10 +954,10 @@ Call <xref:System.Diagnostics.DiagnosticSource.StopActivity%2A?displayProperty=n
         <summary>Gets the W3C <see langword="tracestate" /> header.</summary>
         <value>The W3C <see langword="tracestate" /> header.</value>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 The `tracestate` header is intended to carry supplemental information to trace identity contained in the trace parent. `tracestate` consists of a list of key/value pairs that convey information about the request position in multiple distributed tracing graphs. This information is typically used by distributed tracing systems and should not be used for general purpose baggage, since this may break the correlation of a distributed trace.
-            
+
 Logically `TraceStateString` is just a kind of baggage (if flows just like baggage), but because it is expected to be special-cased (it has its own HTTP header), it is more convenient/efficient if it is not lumped in with other baggage.
 
          ]]></format>

xml/System.Diagnostics/Activity.xml

@@ -1522,7 +1522,7 @@ Entries must be added in the same order as the corresponding nested type definit
 
 ## Remarks
 
-Entries should be added in the same order as the corresponding <see langword="MoveNext" /> method definitions.
+Entries should be added in the same order as the corresponding `MoveNext` method definitions.
 
           ]]></format>
         </remarks>

xml/System.Reflection.Metadata.Ecma335/MetadataBuilder.xml

@@ -21,7 +21,7 @@
   <Docs>
     <summary>Represents a closed universe of Type objects loaded for inspection-only purposes. Each MetadataLoadContext can have its own binding rules and is isolated from all other MetadataLoadContexts.</summary>
     <remarks>
-      <format type="text/markdown"><![CDATA[  
+      <format type="text/markdown"><![CDATA[
 
 ## Remarks
 
@@ -81,18 +81,18 @@ Assemblies are treated strictly as metadata. There are no restrictions on loadin
 ## Remarks
 
 The core assembly is treated differently than other assemblies because references to these well-known types do not include the assembly reference, unlike normal types.
-            
+
 Typically, this assembly is named "mscorlib" or "netstandard". If the core assembly cannot be found, the value will be `null`, and many other reflection methods, including those that parse method signatures, will throw an exception.
-            
+
 The `CoreAssembly` is determined by passing the `coreAssemblyName` parameter passed to the <xref:System.Reflection.MetadataAssemblyResolver> constructor
 to the <xref:System.Reflection.MetadataAssemblyResolver.Resolve%2A?displayProperty=nameWithType> method.
 
 If no `coreAssemblyName` argument was specified in the constructor of <xref:System.Reflection.MetadataLoadContext>, then default values are used, including "mscorlib", "System.Runtime" and "netstandard".
-            
+
 The designated core assembly does not need to contain the core types directly. It can type forward them to other assemblies. Thus, it is perfectly permissible to use the mscorlib facade as the designated core assembly.
-            
+
 Note that <xref:System.Runtime> is not an ideal core assembly because it excludes some of the interop-related pseudo-custom attribute types such as <xref:System.Runtime.InteropServices.DllImportAttribute>. However, it can serve if you have no interest in those attributes. The CustomAttributes API will skip those attributes if the core assembly does not include the necessary types.
-            
+
 The core assembly is not loaded until necessary. The following APIs do not trigger the search for the core assembly:
 
 * <xref:System.Reflection.MetadataLoadContext.LoadFromStream%2A?displayProperty=nameWithType>
@@ -109,9 +109,9 @@ The core assembly is not loaded until necessary. The following APIs do not trigg
 * <xref:System.Type.Name?displayProperty=nameWithType>
 * <xref:System.Type.FullName?displayProperty=nameWithType>
 * <xref:System.Type.AssemblyQualifiedName?displayProperty=nameWithType>
-            
+
 If a core assembly cannot be found or if the core assembly is missing types, this will affect the behavior of the <xref:System.Reflection.MetadataLoadContext> as follows:
-            
+
 * APIs that need to parse signatures or typespecs and return the results as <xref:System.Type> objects will throw an exception. For example:
 
   * <xref:System.Reflection.MethodInfo.ReturnType?displayProperty=nameWithType>
@@ -120,7 +120,7 @@ If a core assembly cannot be found or if the core assembly is missing types, thi
   * <xref:System.Type.GetInterfaces%2A?displayProperty=nameWithType>
 
 * APIs that need to compare types to well-known core types will not throw an exception, and the comparison will evaluate to `false`. For example, if you do not specify a core assembly, <xref:System.Type.IsPrimitive> will return `false` for everything, even types named <xref:System.Int32>. Similarly, <xref:System.Type.GetTypeCode%2A?displayProperty=nameWithType> will return <xref:System.TypeCode.Object> for everything.
-            
+
 * If a metadata entity sets flags that surface as a pseudo-custom attribute, and the core assembly does not contain the pseudo-custom attribute type, the necessary constructor or any of the parameter types of the constructor, the <xref:System.Reflection.MetadataLoadContext> will not throw. It will omit the pseudo-custom attribute from the list of returned attributes.
           ]]></format>
         </remarks>
@@ -149,7 +149,7 @@ If a core assembly cannot be found or if the core assembly is missing types, thi
       <Docs>
         <summary>Releases any native resources (such as file locks on assembly files). </summary>
         <remarks>
-          <format type="text/markdown"><![CDATA[  
+          <format type="text/markdown"><![CDATA[
 
 After disposal, it is not safe to use any <xref:System.Reflection.Assembly> objects dispensed by the <xref:System.Reflection.MetadataLoadContext> or any reflection objects dispensed by those <xref:System.Reflection.Assembly> objects.
 
@@ -208,7 +208,8 @@ Some APIs may return fixed or previously cached data. Accessing objects *during*
         <remarks>
           <format type="text/markdown"><![CDATA[
 ## Remarks
-Note that the behavior of this method matches the behavior of the <xref:System.Runtime.Loader.AssemblyLoadContext.LoadFromAssemblyName%2A?displayProperty=nameWithType> resolve event but does not match the behavior of <xref:System.Reflection.Assembly.ReflectionOnlyLoad%2A?displayProperty=nameWithType>. (The latter gives up without raising its resolve event.)
+
+Note that the behavior of this method matches the behavior of the <xref:System.Runtime.Loader.AssemblyLoadContext.LoadFromAssemblyName%2A?displayProperty=nameWithType> resolve event, but does not match the behavior of <xref:System.Reflection.Assembly.ReflectionOnlyLoad%2A?displayProperty=nameWithType>. (The latter gives up without raising its resolve event.)
           ]]></format>
         </remarks>
         <exception cref="T:System.IO.FileNotFoundException">The resolver returns <see langword="null" />.</exception>