From a61d9b6921c0637581f50e5945f4be759d9bab44 Mon Sep 17 00:00:00 2001
From: Ryan Brandenburg <rybrande@microsoft.com>
Date: Thu, 27 Jun 2019 15:58:43 -0700
Subject: [PATCH] Add some missing doc comments \n\nCommit migrated from
 https://github.com/dotnet/extensions/commit/238b272238ff4382df9a2fc5c7d92a0d68aafa97

---
 .../Abstractions/src/LocalizedString.cs          | 10 +++++++---
 .../src/StringLocalizerExtensions.cs             |  7 +++++--
 .../Localization/src/LocalizationOptions.cs      |  6 ++++++
 .../Localization/src/ResourceNamesCache.cs       | 11 +++++++++--
 src/ObjectPool/src/DefaultObjectPool.cs          | 13 +++++++++++++
 src/ObjectPool/src/DefaultObjectPoolProvider.cs  |  7 +++++++
 src/ObjectPool/src/IPooledObjectPolicy.cs        | 13 +++++++++++++
 src/ObjectPool/src/ObjectPool.cs                 | 16 ++++++++++++++++
 src/ObjectPool/src/ObjectPoolProvider.cs         | 11 +++++++++++
 9 files changed, 87 insertions(+), 7 deletions(-)

diff --git a/src/Localization/Abstractions/src/LocalizedString.cs b/src/Localization/Abstractions/src/LocalizedString.cs
index 6556da40a0..7cac58d16a 100644
--- a/src/Localization/Abstractions/src/LocalizedString.cs
+++ b/src/Localization/Abstractions/src/LocalizedString.cs
@@ -1,5 +1,5 @@
-// Copyright (c) .NET Foundation. All rights reserved. 
-// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. 
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
 
@@ -56,6 +56,10 @@ namespace Microsoft.Extensions.Localization
             SearchedLocation = searchedLocation;
         }
 
+        /// <summary>
+        /// Implicitly converts the <see cref="LocalizedString"/> to a <see cref="string"/>.
+        /// </summary>
+        /// <param name="localizedString">The string to be implicitly converted.</param>
         public static implicit operator string(LocalizedString localizedString)
         {
             return localizedString?.Value;
@@ -87,4 +91,4 @@ namespace Microsoft.Extensions.Localization
         /// <returns>The actual string.</returns>
         public override string ToString() => Value;
     }
-}
\ No newline at end of file
+}
diff --git a/src/Localization/Abstractions/src/StringLocalizerExtensions.cs b/src/Localization/Abstractions/src/StringLocalizerExtensions.cs
index bde47f74f3..3a57475334 100644
--- a/src/Localization/Abstractions/src/StringLocalizerExtensions.cs
+++ b/src/Localization/Abstractions/src/StringLocalizerExtensions.cs
@@ -1,11 +1,14 @@
-// Copyright (c) .NET Foundation. All rights reserved. 
-// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. 
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
 using System.Collections.Generic;
 
 namespace Microsoft.Extensions.Localization
 {
+    /// <summary>
+    /// Extension methods for operating on <see cref="IStringLocalizer" />'s.
+    /// </summary>
     public static class StringLocalizerExtensions
     {
         /// <summary>
diff --git a/src/Localization/Localization/src/LocalizationOptions.cs b/src/Localization/Localization/src/LocalizationOptions.cs
index 1b7408fe67..1c0b82d210 100644
--- a/src/Localization/Localization/src/LocalizationOptions.cs
+++ b/src/Localization/Localization/src/LocalizationOptions.cs
@@ -8,6 +8,12 @@ namespace Microsoft.Extensions.Localization
     /// </summary>
     public class LocalizationOptions
     {
+        /// <summary>
+        /// Creates a new <see cref="LocalizationOptions" />.
+        /// </summary>
+        public LocalizationOptions()
+        { }
+
         /// <summary>
         /// The relative path under application root where resource files are located.
         /// </summary>
diff --git a/src/Localization/Localization/src/ResourceNamesCache.cs b/src/Localization/Localization/src/ResourceNamesCache.cs
index 86e94c102a..72b7986d9f 100644
--- a/src/Localization/Localization/src/ResourceNamesCache.cs
+++ b/src/Localization/Localization/src/ResourceNamesCache.cs
@@ -1,5 +1,5 @@
-// Copyright (c) .NET Foundation. All rights reserved. 
-// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information. 
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
 
 using System;
 using System.Collections.Concurrent;
@@ -14,6 +14,13 @@ namespace Microsoft.Extensions.Localization
     {
         private readonly ConcurrentDictionary<string, IList<string>> _cache = new ConcurrentDictionary<string, IList<string>>();
 
+        /// <summary>
+        /// Creates a new <see cref="ResourceNamesCache" />
+        /// </summary>
+        public ResourceNamesCache()
+        {
+        }
+
         /// <inheritdoc />
         public IList<string> GetOrAdd(string name, Func<string, IList<string>> valueFactory)
         {
diff --git a/src/ObjectPool/src/DefaultObjectPool.cs b/src/ObjectPool/src/DefaultObjectPool.cs
index 070508a014..0ab6ed7608 100644
--- a/src/ObjectPool/src/DefaultObjectPool.cs
+++ b/src/ObjectPool/src/DefaultObjectPool.cs
@@ -8,6 +8,10 @@ using System.Threading;
 
 namespace Microsoft.Extensions.ObjectPool
 {
+    /// <summary>
+    /// Default implementation of <see cref="ObjectPool<T>"/>.
+    /// </summary>
+    /// <typeparam name="T">The type to pool objects for.</typeparam>
     public class DefaultObjectPool<T> : ObjectPool<T> where T : class
     {
         private protected readonly ObjectWrapper[] _items;
@@ -18,11 +22,20 @@ namespace Microsoft.Extensions.ObjectPool
         // This class was introduced in 2.1 to avoid the interface call where possible
         private protected readonly PooledObjectPolicy<T> _fastPolicy;
 
+        /// <summary>
+        /// Creates an instance of <see cref="DefaultObjectPool<T>"/>.
+        /// </summary>
+        /// <param name="policy">The pooling policy to use.</param>
         public DefaultObjectPool(IPooledObjectPolicy<T> policy)
             : this(policy, Environment.ProcessorCount * 2)
         {
         }
 
+        /// <summary>
+        /// Creates an instance of <see cref="DefaultObjectPool<T>"/>.
+        /// </summary>
+        /// <param name="policy">The pooling policy to use.</param>
+        /// <param name="maximumRetained">The maximum number of objects to retain in the pool.</param>
         public DefaultObjectPool(IPooledObjectPolicy<T> policy, int maximumRetained)
         {
             _policy = policy ?? throw new ArgumentNullException(nameof(policy));
diff --git a/src/ObjectPool/src/DefaultObjectPoolProvider.cs b/src/ObjectPool/src/DefaultObjectPoolProvider.cs
index 2e7767ab35..f5085c26ef 100644
--- a/src/ObjectPool/src/DefaultObjectPoolProvider.cs
+++ b/src/ObjectPool/src/DefaultObjectPoolProvider.cs
@@ -5,10 +5,17 @@ using System;
 
 namespace Microsoft.Extensions.ObjectPool
 {
+    /// <summary>
+    /// A provider of <see cref="DefaultObjectPool<T>"/>'s.
+    /// </summary>
     public class DefaultObjectPoolProvider : ObjectPoolProvider
     {
+        /// <summary>
+        /// The maximum number of objects to retain in the pool.
+        /// </summary>
         public int MaximumRetained { get; set; } = Environment.ProcessorCount * 2;
 
+        /// <inheritdoc/>
         public override ObjectPool<T> Create<T>(IPooledObjectPolicy<T> policy)
         {
             if (policy == null)
diff --git a/src/ObjectPool/src/IPooledObjectPolicy.cs b/src/ObjectPool/src/IPooledObjectPolicy.cs
index 54611bad30..7bd9b9394a 100644
--- a/src/ObjectPool/src/IPooledObjectPolicy.cs
+++ b/src/ObjectPool/src/IPooledObjectPolicy.cs
@@ -3,10 +3,23 @@
 
 namespace Microsoft.Extensions.ObjectPool
 {
+    /// <summary>
+    /// Represents a policy for managing pooled objects.
+    /// </summary>
+    /// <typeparam name="T">The type of object which is being pooled.</typeparam>
     public interface IPooledObjectPolicy<T>
     {
+        /// <summary>
+        /// Create a <typeparamref name="T"/>.
+        /// </summary>
+        /// <returns>The <typeparamref name="T"/> which was created.</returns>
         T Create();
 
+        /// <summary>
+        /// Put an object in the pool.
+        /// </summary>
+        /// <param name="obj">The object to put in the pool.</param>
+        /// <returns><code>true</code> if put in the pool.</returns>
         bool Return(T obj);
     }
 }
diff --git a/src/ObjectPool/src/ObjectPool.cs b/src/ObjectPool/src/ObjectPool.cs
index 691beae60c..f7065c2223 100644
--- a/src/ObjectPool/src/ObjectPool.cs
+++ b/src/ObjectPool/src/ObjectPool.cs
@@ -3,15 +3,31 @@
 
 namespace Microsoft.Extensions.ObjectPool
 {
+    /// <summary>
+    /// A pool of objects.
+    /// </summary>
+    /// <typeparam name="T">The type of objects to pool.</typeparam>
     public abstract class ObjectPool<T> where T : class
     {
+        /// <summary>
+        /// Returns an object from the pool.
+        /// </summary>
+        /// <returns>An object from the pool.</returns>
         public abstract T Get();
 
+        /// <summary>
+        /// Put an object in the pool.
+        /// </summary>
+        /// <param name="obj">The object to add to the pool.</param>
         public abstract void Return(T obj);
     }
 
+    /// <summary>
+    /// Methods for creating <see cref="ObjectPool<T>"/>'s.
+    /// </summary>
     public static class ObjectPool
     {
+        /// <inheritdoc />
         public static ObjectPool<T> Create<T>(IPooledObjectPolicy<T> policy = null) where T : class, new()
         {
             var provider = new DefaultObjectPoolProvider();
diff --git a/src/ObjectPool/src/ObjectPoolProvider.cs b/src/ObjectPool/src/ObjectPoolProvider.cs
index 909795dd35..36db247bfe 100644
--- a/src/ObjectPool/src/ObjectPoolProvider.cs
+++ b/src/ObjectPool/src/ObjectPoolProvider.cs
@@ -3,13 +3,24 @@
 
 namespace Microsoft.Extensions.ObjectPool
 {
+    /// <summary>
+    /// A provider of <see cref="ObjectPool<T>"/>'s.
+    /// </summary>
     public abstract class ObjectPoolProvider
     {
+        /// <summary>
+        /// Creates an <see cref="ObjectPool"/>.
+        /// </summary>
+        /// <typeparam name="T">The type to create a pool for.</typeparam>
         public ObjectPool<T> Create<T>() where T : class, new()
         {
             return Create<T>(new DefaultPooledObjectPolicy<T>());
         }
 
+        /// <summary>
+        /// Creates an <see cref="ObjectPool"/> with the given <see cref="IPooledObjectPolicy<T>"/>.
+        /// </summary>
+        /// <typeparam name="T">The type to create a pool for.</typeparam>
         public abstract ObjectPool<T> Create<T>(IPooledObjectPolicy<T> policy) where T : class;
     }
 }