PR feedback

\n\nCommit migrated from d656c4f7e2

src/Localization/Abstractions/src/StringLocalizerExtensions.cs

@@ -7,7 +7,7 @@ using System.Collections.Generic;
 namespace Microsoft.Extensions.Localization
 {
     /// <summary>
-    /// Extension methods for operating on <see cref="IStringLocalizer" />'s.
+    /// Extension methods for operating on <see cref="IStringLocalizer" /> instances.
     /// </summary>
     public static class StringLocalizerExtensions
     {

src/ObjectPool/src/DefaultObjectPool.cs

@@ -12,6 +12,7 @@ namespace Microsoft.Extensions.ObjectPool
     /// Default implementation of <see cref="ObjectPool{T}"/>.
     /// </summary>
     /// <typeparam name="T">The type to pool objects for.</typeparam>
+    /// <remarks>This implementation keeps a cache of retained objects. This means that if objects are returned when the pool has already reached "maximumRetained" objects they will be available to be Garbage Collected.</remarks>
     public class DefaultObjectPool<T> : ObjectPool<T> where T : class
     {
         private protected readonly ObjectWrapper[] _items;

src/ObjectPool/src/DefaultObjectPoolProvider.cs

@@ -6,7 +6,7 @@ using System;
 namespace Microsoft.Extensions.ObjectPool
 {
     /// <summary>
-    /// A provider of <see cref="DefaultObjectPool{T}"/>'s.
+    /// The default <see cref="ObjectPoolProvider"/>.
     /// </summary>
     public class DefaultObjectPoolProvider : ObjectPoolProvider
     {

src/ObjectPool/src/IPooledObjectPolicy.cs

@@ -16,10 +16,10 @@ namespace Microsoft.Extensions.ObjectPool
         T Create();
 
         /// <summary>
-        /// Return an object to the pool.
+        /// Runs some processing when an object was returned to the pool. Can be used to reset the state of an object and indicate if the object should be returned to the pool.
         /// </summary>
         /// <param name="obj">The object to return to the pool.</param>
-        /// <returns><code>true</code> if returned to the pool.</returns>
+        /// <returns><code>true</code> if the object should be returned to the pool. <code>false</code> if it's not possible/desirable for the pool to keep the object.</returns>
         bool Return(T obj);
     }
 }

src/ObjectPool/src/ObjectPool.cs

@@ -23,7 +23,7 @@ namespace Microsoft.Extensions.ObjectPool
     }
 
     /// <summary>
-    /// Methods for creating <see cref="ObjectPool{T}"/>'s.
+    /// Methods for creating <see cref="ObjectPool{T}"/> instances.
     /// </summary>
     public static class ObjectPool
     {

src/ObjectPool/src/ObjectPoolProvider.cs

@@ -4,7 +4,7 @@
 namespace Microsoft.Extensions.ObjectPool
 {
     /// <summary>
-    /// A provider of <see cref="ObjectPool{T}"/>'s.
+    /// A provider of <see cref="ObjectPool{T}"/> instances.
     /// </summary>
     public abstract class ObjectPoolProvider
     {