Add missing API documentation for Microsoft.Extensions.FileProvider

src/libraries/Microsoft.Extensions.FileProviders.Abstractions/src/NotFoundDirectoryContents.cs

@@ -12,6 +12,11 @@ namespace Microsoft.Extensions.FileProviders
     /// </summary>
     public class NotFoundDirectoryContents : IDirectoryContents
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="NotFoundDirectoryContents"/> class.
+        /// </summary>
+        public NotFoundDirectoryContents() { }
+
         /// <summary>
         /// Gets a shared instance of <see cref="NotFoundDirectoryContents"/>.
         /// </summary>

src/libraries/Microsoft.Extensions.FileProviders.Abstractions/src/NotFoundFileInfo.cs

@@ -13,7 +13,7 @@ namespace Microsoft.Extensions.FileProviders
     public class NotFoundFileInfo : IFileInfo
     {
         /// <summary>
-        /// Initializes an instance of <see cref="NotFoundFileInfo"/>.
+        /// Initializes a new instance of the <see cref="NotFoundFileInfo"/> class.
         /// </summary>
         /// <param name="name">The name of the file that could not be found.</param>
         public NotFoundFileInfo(string name)

src/libraries/Microsoft.Extensions.FileProviders.Abstractions/src/NullFileProvider.cs

@@ -10,6 +10,11 @@ namespace Microsoft.Extensions.FileProviders
     /// </summary>
     public class NullFileProvider : IFileProvider
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="NullFileProvider"/> class.
+        /// </summary>
+        public NullFileProvider() { }
+
         /// <summary>
         /// Enumerates a nonexistent directory.
         /// </summary>

src/libraries/Microsoft.Extensions.FileProviders.Composite/src/CompositeDirectoryContents.cs

@@ -21,7 +21,7 @@ public class CompositeDirectoryContents : IDirectoryContents
         private List<IDirectoryContents>? _directories;
 
         /// <summary>
-        /// Creates a new instance of <see cref="CompositeDirectoryContents"/> to represents the result of a call composition of
+        /// Initializes a new instance of the <see cref="CompositeDirectoryContents"/> class to represent the result of a call composition of
         /// <see cref="IFileProvider.GetDirectoryContents(string)"/>.
         /// </summary>
         /// <param name="fileProviders">The list of <see cref="IFileProvider"/> for which the results have to be composed.</param>

src/libraries/Microsoft.Extensions.FileProviders.Physical/src/Internal/PhysicalDirectoryContents.cs

@@ -17,18 +17,18 @@ public class PhysicalDirectoryContents : IDirectoryContents
         private readonly PhysicalDirectoryInfo _info;
 
         /// <summary>
-        /// Initializes an instance of <see cref="PhysicalDirectoryContents"/>.
+        /// Initializes a new instance of the <see cref="PhysicalDirectoryContents"/> class.
         /// </summary>
         /// <param name="directory">The directory to represent.</param>
         public PhysicalDirectoryContents(string directory)
             : this(directory, ExclusionFilters.Sensitive)
         { }
 
         /// <summary>
-        /// Initializes an instance of <see cref="PhysicalDirectoryContents"/>.
+        /// Initializes a new instance of the <see cref="PhysicalDirectoryContents"/> class.
         /// </summary>
         /// <param name="directory">The directory to represent.</param>
-        /// <param name="filters">Specifies which files or directories are excluded from enumeration.</param>
+        /// <param name="filters">A bitwise combination of the enumeration values that specifies which files or directories are excluded from enumeration.</param>
         public PhysicalDirectoryContents(string directory, ExclusionFilters filters)
         {
             ArgumentNullException.ThrowIfNull(directory);

src/libraries/Microsoft.Extensions.FileProviders.Physical/src/PhysicalDirectoryInfo.cs

@@ -20,7 +20,7 @@ public class PhysicalDirectoryInfo : IFileInfo, IDirectoryContents
         private readonly ExclusionFilters _filters;
 
         /// <summary>
-        /// Initializes an instance of <see cref="PhysicalDirectoryInfo"/> that wraps an instance of <see cref="System.IO.DirectoryInfo"/>.
+        /// Initializes a new instance of the <see cref="PhysicalDirectoryInfo"/> class that wraps an instance of <see cref="System.IO.DirectoryInfo"/>.
         /// </summary>
         /// <param name="info">The directory to represent.</param>
         public PhysicalDirectoryInfo(DirectoryInfo info)

src/libraries/Microsoft.Extensions.FileProviders.Physical/src/PhysicalFileInfo.cs

@@ -14,7 +14,7 @@ public class PhysicalFileInfo : IFileInfo
         private readonly FileInfo _info;
 
         /// <summary>
-        /// Initializes an instance of <see cref="PhysicalFileInfo"/> that wraps an instance of <see cref="System.IO.FileInfo"/>.
+        /// Initializes a new instance of the <see cref="PhysicalFileInfo"/> class that wraps an instance of <see cref="System.IO.FileInfo"/>.
         /// </summary>
         /// <param name="info">The <see cref="System.IO.FileInfo"/>.</param>
         public PhysicalFileInfo(FileInfo info)

src/libraries/Microsoft.Extensions.FileProviders.Physical/src/PhysicalFileProvider.cs

@@ -38,7 +38,7 @@ public class PhysicalFileProvider : IFileProvider, IDisposable
         private bool _disposed;
 
         /// <summary>
-        /// Initializes a new instance of a PhysicalFileProvider at the given root directory.
+        /// Initializes a new instance of the <see cref="PhysicalFileProvider"/> class at the given root directory.
         /// </summary>
         /// <param name="root">The root directory. This should be an absolute path.</param>
         public PhysicalFileProvider(string root)
@@ -47,10 +47,10 @@ public PhysicalFileProvider(string root)
         }
 
         /// <summary>
-        /// Initializes a new instance of a PhysicalFileProvider at the given root directory.
+        /// Initializes a new instance of the <see cref="PhysicalFileProvider"/> class at the given root directory.
         /// </summary>
         /// <param name="root">The root directory. This should be an absolute path.</param>
-        /// <param name="filters">Specifies which files or directories are excluded.</param>
+        /// <param name="filters">A bitwise combination of the enumeration values that specifies which files or directories are excluded.</param>
         public PhysicalFileProvider(string root, ExclusionFilters filters)
         {
             if (!Path.IsPathRooted(root))
@@ -207,7 +207,7 @@ public void Dispose()
         /// <summary>
         /// Disposes the provider.
         /// </summary>
-        /// <param name="disposing"><c>true</c> is invoked from <see cref="IDisposable.Dispose"/>.</param>
+        /// <param name="disposing"><see langword="true"/> if invoked from <see cref="IDisposable.Dispose"/>; otherwise, <see langword="false"/>.</param>
         protected virtual void Dispose(bool disposing)
         {
             if (!_disposed)

src/libraries/Microsoft.Extensions.FileProviders.Physical/src/PhysicalFilesWatcher.cs

@@ -41,14 +41,14 @@ public class PhysicalFilesWatcher : IDisposable
         private bool _disposed;
 
         /// <summary>
-        /// Initializes an instance of <see cref="PhysicalFilesWatcher" /> that watches files in <paramref name="root" />.
-        /// Wraps an instance of <see cref="System.IO.FileSystemWatcher" />.
+        /// Initializes a new instance of the <see cref="PhysicalFilesWatcher"/> class that watches files in <paramref name="root"/>.
+        /// Wraps an instance of <see cref="System.IO.FileSystemWatcher"/>.
         /// </summary>
-        /// <param name="root">Root directory for the watcher.</param>
-        /// <param name="fileSystemWatcher">The wrapped watcher that's watching <paramref name="root" />.</param>
+        /// <param name="root">The root directory for the watcher.</param>
+        /// <param name="fileSystemWatcher">The wrapped watcher that's watching <paramref name="root"/>.</param>
         /// <param name="pollForChanges">
         /// <see langword="true"/> for the poller to use polling to trigger instances of
-        /// <see cref="IChangeToken" /> created by <see cref="CreateFileChangeToken(string)" />.
+        /// <see cref="IChangeToken"/> created by <see cref="CreateFileChangeToken(string)"/>; otherwise, <see langword="false"/>.
         /// </param>
         public PhysicalFilesWatcher(
             string root,
@@ -59,16 +59,16 @@ public PhysicalFilesWatcher(
         }
 
         /// <summary>
-        /// Initializes an instance of <see cref="PhysicalFilesWatcher" /> that watches files in <paramref name="root" />.
-        /// Wraps an instance of <see cref="System.IO.FileSystemWatcher" />.
+        /// Initializes a new instance of the <see cref="PhysicalFilesWatcher"/> class that watches files in <paramref name="root"/>.
+        /// Wraps an instance of <see cref="System.IO.FileSystemWatcher"/>.
         /// </summary>
-        /// <param name="root">Root directory for the watcher.</param>
-        /// <param name="fileSystemWatcher">The wrapped watcher that is watching <paramref name="root" />.</param>
+        /// <param name="root">The root directory for the watcher.</param>
+        /// <param name="fileSystemWatcher">The wrapped watcher that is watching <paramref name="root"/>.</param>
         /// <param name="pollForChanges">
         /// <see langword="true"/> for the poller to use polling to trigger instances of
-        /// <see cref="IChangeToken" /> created by <see cref="CreateFileChangeToken(string)" />.
+        /// <see cref="IChangeToken"/> created by <see cref="CreateFileChangeToken(string)"/>; otherwise, <see langword="false"/>.
         /// </param>
-        /// <param name="filters">Specifies which files or directories are excluded. Notifications of changes to are not raised to these.</param>
+        /// <param name="filters">A bitwise combination of the enumeration values that specifies which files or directories are excluded. Notifications of changes to these are not raised.</param>
         public PhysicalFilesWatcher(
             string root,
             FileSystemWatcher? fileSystemWatcher,
@@ -247,7 +247,7 @@ public void Dispose()
         /// <summary>
         /// Disposes the provider.
         /// </summary>
-        /// <param name="disposing"><c>true</c> is invoked from <see cref="IDisposable.Dispose"/>.</param>
+        /// <param name="disposing"><see langword="true"/> if invoked from <see cref="IDisposable.Dispose"/>; otherwise, <see langword="false"/>.</param>
         protected virtual void Dispose(bool disposing)
         {
             if (!_disposed)

src/libraries/Microsoft.Extensions.FileProviders.Physical/src/PollingFileChangeToken.cs

@@ -15,8 +15,10 @@ namespace Microsoft.Extensions.FileProviders.Physical
     /// </summary>
     /// <remarks>
     /// <para>Polling occurs every 4 seconds.</para>
-    /// <para>This change token does not raise any change callbacks. Callers should watch for <see cref="HasChanged" /> to turn
-    /// from <see langword="false"/> to <see langword="true"/> and dispose the token after this happens.</para>
+    /// <para>By default, this change token does not raise change callbacks. Callers should watch for <see cref="HasChanged" /> to turn
+    /// from <see langword="false"/> to <see langword="true"/>.
+    /// When <see cref="ActiveChangeCallbacks"/> is <see langword="true"/>, callbacks registered via
+    /// <see cref="RegisterChangeCallback"/> will be invoked when the file changes.</para>
     /// </remarks>
     public class PollingFileChangeToken : IPollingChangeToken
     {
@@ -28,8 +30,8 @@ public class PollingFileChangeToken : IPollingChangeToken
         private CancellationChangeToken? _changeToken;
 
         /// <summary>
-        /// Initializes a new instance of <see cref="PollingFileChangeToken" /> that polls the specified file for changes as
-        /// determined by <see cref="System.IO.FileSystemInfo.LastWriteTimeUtc" />.
+        /// Initializes a new instance of the <see cref="PollingFileChangeToken"/> class that polls the specified file for changes as
+        /// determined by <see cref="System.IO.FileSystemInfo.LastWriteTimeUtc"/>.
         /// </summary>
         /// <param name="fileInfo">The <see cref="System.IO.FileInfo"/> to poll.</param>
         public PollingFileChangeToken(FileInfo fileInfo)
@@ -54,7 +56,8 @@ private DateTime GetLastWriteTimeUtc()
         }
 
         /// <summary>
-        /// Gets a value that's always <see langword="false"/>.
+        /// Gets a value that indicates whether this token will proactively raise callbacks. If <see langword="false"/>, the token
+        /// consumer must poll <see cref="HasChanged"/> to detect changes.
         /// </summary>
         public bool ActiveChangeCallbacks { get; internal set; }
 
@@ -108,10 +111,11 @@ public bool HasChanged
         }
 
         /// <summary>
-        /// Does not actually register callbacks.
+        /// Registers a callback that will be invoked when the token changes, if <see cref="ActiveChangeCallbacks"/> is <see langword="true"/>.
+        /// If <see cref="ActiveChangeCallbacks"/> is <see langword="false"/>, no callback is registered and an empty disposable is returned.
         /// </summary>
-        /// <param name="callback">This parameter is ignored.</param>
-        /// <param name="state">This parameter is ignored.</param>
+        /// <param name="callback">The callback to invoke. This parameter is ignored when <see cref="ActiveChangeCallbacks"/> is <see langword="false"/>.</param>
+        /// <param name="state">The state to pass to <paramref name="callback"/>. This parameter is ignored when <see cref="ActiveChangeCallbacks"/> is <see langword="false"/>.</param>
         /// <returns>A disposable object that no-ops when disposed.</returns>
         public IDisposable RegisterChangeCallback(Action<object?> callback, object? state)
         {

src/libraries/Microsoft.Extensions.FileProviders.Physical/src/PollingWildCardChangeToken.cs

@@ -34,7 +34,7 @@ public class PollingWildCardChangeToken : IPollingChangeToken
         private CancellationChangeToken? _changeToken;
 
         /// <summary>
-        /// Initializes a new instance of <see cref="PollingWildCardChangeToken"/>.
+        /// Initializes a new instance of the <see cref="PollingWildCardChangeToken"/> class.
         /// </summary>
         /// <param name="root">The root of the file system.</param>
         /// <param name="pattern">The pattern to watch.</param>