Add missing xml docs for all file provider implementations (#227)

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

@@ -73,6 +73,11 @@ private void EnsureFilesAreInitialized()
             }
         }
 
+        /// <summary>
+        /// Creates an enumerator for all files in all providers given.
+        /// Ensures each item in the collection is distinct.
+        /// </summary>
+        /// <returns>An enumerator over all files in all given providers</returns>
         public IEnumerator<IFileInfo> GetEnumerator()
         {
             EnsureFilesAreInitialized();
@@ -85,6 +90,9 @@ IEnumerator IEnumerable.GetEnumerator()
             return _files.GetEnumerator();
         }
 
+        /// <summary>
+        /// True if any given providers exists
+        /// </summary>
         public bool Exists
         {
             get

src/Microsoft.Extensions.FileProviders.Composite/CompositeFileProvider.cs

@@ -10,25 +10,25 @@
 namespace Microsoft.Extensions.FileProviders
 {
     /// <summary>
-    /// Looks up files using a list of <see cref="IFileProvider"/>.
+    /// Looks up files using a collection of <see cref="IFileProvider"/>.
     /// </summary>
     public class CompositeFileProvider : IFileProvider
     {
         private readonly IFileProvider[] _fileProviders;
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="CompositeFileProvider" /> class using a list of file provider.
+        /// Initializes a new instance of the <see cref="CompositeFileProvider" /> class using a collection of file provider.
         /// </summary>
-        /// <param name="fileProviders"></param>
+        /// <param name="fileProviders">The collection of <see cref="IFileProvider" /></param>
         public CompositeFileProvider(params IFileProvider[] fileProviders)
         {
             _fileProviders = fileProviders ?? new IFileProvider[0];
         }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="CompositeFileProvider" /> class using a list of file provider.
+        /// Initializes a new instance of the <see cref="CompositeFileProvider" /> class using a collection of file provider.
         /// </summary>
-        /// <param name="fileProviders"></param>
+        /// <param name="fileProviders">The collection of <see cref="IFileProvider" /></param>
         public CompositeFileProvider(IEnumerable<IFileProvider> fileProviders)
         {
             if (fileProviders == null)

src/Microsoft.Extensions.FileProviders.Composite/project.json

@@ -3,9 +3,6 @@
   "buildOptions": {
     "warningsAsErrors": true,
     "keyFile": "../../tools/Key.snk",
-    "nowarn": [
-      "CS1591"
-    ],
     "xmlDoc": true
   },
   "description": "Composite file and directory providers for Microsoft.Extensions.FileProviders.",

src/Microsoft.Extensions.FileProviders.Embedded/EmbeddedFileProvider.cs

@@ -20,6 +20,7 @@ public class EmbeddedFileProvider : IFileProvider
     {
         private static readonly char[] _invalidFileNameChars = Path.GetInvalidFileNameChars()
             .Where(c => c != '/' && c != '\\').ToArray();
+
         private readonly Assembly _assembly;
         private readonly string _baseNamespace;
         private readonly DateTimeOffset _lastModified;
@@ -28,7 +29,7 @@ public class EmbeddedFileProvider : IFileProvider
         /// Initializes a new instance of the <see cref="EmbeddedFileProvider" /> class using the specified
         /// assembly and empty base namespace.
         /// </summary>
-        /// <param name="assembly"></param>
+        /// <param name="assembly">The assembly that contains the embedded resources.</param>
         public EmbeddedFileProvider(Assembly assembly)
             : this(assembly, assembly?.GetName()?.Name)
         {
@@ -75,7 +76,10 @@ public EmbeddedFileProvider(Assembly assembly, string baseNamespace)
         /// Locates a file at the given path.
         /// </summary>
         /// <param name="subpath">The path that identifies the file. </param>
-        /// <returns>The file information. Caller must check Exists property.</returns>
+        /// <returns>
+        /// The file information. Caller must check Exists property. A <see cref="NotFoundFileInfo" /> if the file could
+        /// not be found.
+        /// </returns>
         public IFileInfo GetFileInfo(string subpath)
         {
             if (string.IsNullOrEmpty(subpath))
@@ -121,10 +125,14 @@ public IFileInfo GetFileInfo(string subpath)
 
         /// <summary>
         /// Enumerate a directory at the given path, if any.
-        /// This file provider uses a flat directory structure. Everything under the base namespace is considered to be one directory.
+        /// This file provider uses a flat directory structure. Everything under the base namespace is considered to be one
+        /// directory.
         /// </summary>
         /// <param name="subpath">The path that identifies the directory</param>
-        /// <returns>Contents of the directory. Caller must check Exists property.</returns>
+        /// <returns>
+        /// Contents of the directory. Caller must check Exists property. A <see cref="NotFoundDirectoryContents" /> if no
+        /// resources were found that match <paramref name="subpath" />
+        /// </returns>
         public IDirectoryContents GetDirectoryContents(string subpath)
         {
             // The file name is assumed to be the remainder of the resource name.
@@ -165,6 +173,11 @@ public IDirectoryContents GetDirectoryContents(string subpath)
             return new EnumerableDirectoryContents(entries);
         }
 
+        /// <summary>
+        /// Embedded files do not change.
+        /// </summary>
+        /// <param name="pattern">This parameter is ignored</param>
+        /// <returns>A <see cref="NullChangeToken" /></returns>
         public IChangeToken Watch(string pattern)
         {
             return NullChangeToken.Singleton;
@@ -175,4 +188,4 @@ private static bool HasInvalidPathChars(string path)
             return path.IndexOfAny(_invalidFileNameChars) != -1;
         }
     }
-}
+}

src/Microsoft.Extensions.FileProviders.Embedded/EmbeddedResourceFileInfo.cs

@@ -7,13 +7,23 @@
 
 namespace Microsoft.Extensions.FileProviders.Embedded
 {
+    /// <summary>
+    /// Represents a file embedded in an assembly.
+    /// </summary>
     public class EmbeddedResourceFileInfo : IFileInfo
     {
         private readonly Assembly _assembly;
         private readonly string _resourcePath;
 
         private long? _length;
 
+        /// <summary>
+        /// Initializes a new instance of <see cref="EmbeddedFileProvider"/> for an assembly using <paramref name="resourcePath"/> as the base
+        /// </summary>
+        /// <param name="assembly">The assembly that contains the embedded resource</param>
+        /// <param name="resourcePath">The path to the embedded resource</param>
+        /// <param name="name">An arbitrary name for this instance</param>
+        /// <param name="lastModified">The <see cref="DateTimeOffset" /> to use for <see cref="LastModified" /></param>
         public EmbeddedResourceFileInfo(
             Assembly assembly,
             string resourcePath,
@@ -26,8 +36,14 @@ public EmbeddedResourceFileInfo(
             LastModified = lastModified;
         }
 
+        /// <summary>
+        /// Always true.
+        /// </summary>
         public bool Exists => true;
 
+        /// <summary>
+        /// The length, in bytes, of the embedded resource
+        /// </summary>
         public long Length
         {
             get
@@ -43,15 +59,27 @@ public long Length
             }
         }
 
-        // Not directly accessible.
+        /// <summary>
+        /// Always null.
+        /// </summary>
         public string PhysicalPath => null;
 
+        /// <summary>
+        /// The name of embedded file
+        /// </summary>
         public string Name { get; }
 
+        /// <summary>
+        /// The time, in UTC, when the <see cref="EmbeddedFileProvider"/> was created
+        /// </summary>
         public DateTimeOffset LastModified { get; }
 
+        /// <summary>
+        /// Always false.
+        /// </summary>
         public bool IsDirectory => false;
 
+        /// <inheritdoc />
         public Stream CreateReadStream()
         {
             var stream = _assembly.GetManifestResourceStream(_resourcePath);

src/Microsoft.Extensions.FileProviders.Embedded/Microsoft.Extensions.FileProviders.Embedded.xproj

@@ -10,6 +10,9 @@
     <BaseIntermediateOutputPath Condition="'$(BaseIntermediateOutputPath)'=='' ">.\obj</BaseIntermediateOutputPath>
     <OutputPath Condition="'$(OutputPath)'=='' ">.\bin\</OutputPath>
   </PropertyGroup>
+  <PropertyGroup Label="Configuration">
+    <RootNamespace>Microsoft.Extensions.FileProviders</RootNamespace>
+  </PropertyGroup>
   <PropertyGroup>
     <SchemaVersion>2.0</SchemaVersion>
   </PropertyGroup>

src/Microsoft.Extensions.FileProviders.Embedded/project.json

@@ -3,9 +3,6 @@
   "buildOptions": {
     "warningsAsErrors": true,
     "keyFile": "../../tools/Key.snk",
-    "nowarn": [
-      "CS1591"
-    ],
     "xmlDoc": true
   },
   "description": "File provider for files in embedded resources for Microsoft.Extensions.FileProviders.",

src/Microsoft.Extensions.FileProviders.Physical/FileSystemInfoHelper.cs

@@ -5,7 +5,10 @@
 
 namespace Microsoft.Extensions.FileProviders
 {
-    public class FileSystemInfoHelper
+    /// <summary>
+    /// Helper functions for working with the filesystem
+    /// </summary>
+    public static class FileSystemInfoHelper
     {
         internal static bool IsHiddenFile(FileSystemInfo fileSystemInfo)
         {

src/Microsoft.Extensions.FileProviders.Physical/Microsoft.Extensions.FileProviders.Physical.xproj

@@ -10,6 +10,9 @@
     <BaseIntermediateOutputPath Condition="'$(BaseIntermediateOutputPath)'=='' ">.\obj</BaseIntermediateOutputPath>
     <OutputPath Condition="'$(OutputPath)'=='' ">.\bin\</OutputPath>
   </PropertyGroup>
+  <PropertyGroup Label="Configuration">
+    <RootNamespace>Microsoft.Extensions.FileProviders</RootNamespace>
+  </PropertyGroup>
   <PropertyGroup>
     <SchemaVersion>2.0</SchemaVersion>
   </PropertyGroup>

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

@@ -6,27 +6,51 @@
 
 namespace Microsoft.Extensions.FileProviders.Physical
 {
+    /// <summary>
+    /// Represents a directory on a physical filesystem
+    /// </summary>
     public class PhysicalDirectoryInfo : IFileInfo
     {
         private readonly DirectoryInfo _info;
 
+        /// <summary>
+        /// Initializes an instance of <see cref="PhysicalDirectoryInfo"/> that wraps an instance of <see cref="System.IO.DirectoryInfo"/>
+        /// </summary>
+        /// <param name="info">The directory</param>
         public PhysicalDirectoryInfo(DirectoryInfo info)
         {
             _info = info;
         }
 
+        /// <inheritdoc />
         public bool Exists => _info.Exists;
 
+        /// <summary>
+        /// Always equals -1.
+        /// </summary>
         public long Length => -1;
 
+        /// <inheritdoc />
         public string PhysicalPath => _info.FullName;
 
+        /// <inheritdoc />
         public string Name => _info.Name;
 
+        /// <summary>
+        /// The time when the directory was last written to.
+        /// </summary>
         public DateTimeOffset LastModified => _info.LastWriteTimeUtc;
 
+        /// <summary>
+        /// Always true.
+        /// </summary>
         public bool IsDirectory => true;
 
+        /// <summary>
+        /// Always throws an exception because read streams are not support on directories.
+        /// </summary>
+        /// <exception cref="InvalidOperationException">Always thrown</exception>
+        /// <returns>Never returns</returns>
         public Stream CreateReadStream()
         {
             throw new InvalidOperationException("Cannot create a stream for a directory.");

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

@@ -6,27 +6,43 @@
 
 namespace Microsoft.Extensions.FileProviders.Physical
 {
+    /// <summary>
+    /// Represents a file on a physical filesystem
+    /// </summary>
     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"/>
+        /// </summary>
+        /// <param name="info">The <see cref="System.IO.FileInfo"/></param>
         public PhysicalFileInfo(FileInfo info)
         {
             _info = info;
         }
 
+        /// <inheritdoc />
         public bool Exists => _info.Exists;
 
+        /// <inheritdoc />
         public long Length => _info.Length;
 
+        /// <inheritdoc />
         public string PhysicalPath => _info.FullName;
 
+        /// <inheritdoc />
         public string Name => _info.Name;
 
+        /// <inheritdoc />
         public DateTimeOffset LastModified => _info.LastWriteTimeUtc;
 
+        /// <summary>
+        /// Always false.
+        /// </summary>
         public bool IsDirectory => false;
 
+        /// <inheritdoc />
         public Stream CreateReadStream()
         {
             // We are setting buffer size to 1 to prevent FileStream from allocating it's internal buffer