API documentation debt - Microsoft.Extensions.FileProvider

[carlossanlop]

Area owners: @maryamariyan @carlossanlop @Jozkee

The APIs in the list below are missing some or all of their documentation. Please add the missing documentation directly in triple slash comments in source. We will make sure it gets ported to dotnet-api-docs after it's merged.

Make sure to follow the documentation guidelines defined in the dotnet-api-docs wiki: https://github.com/dotnet/dotnet-api-docs/wiki

Also please add me as a PR reviewer.

Community contributions are welcome.

Microsoft.Extensions.FileProviders

DocId | Summary | Parameters | TypeParameters | ReturnValue | Source File Path | Docs URL -- | -- | -- | -- | -- | -- | -- Microsoft.Extensions.FileProviders.Physical namespace | Missing | NA | NA | NA | https://github.com/dotnet/dotnet-api-docs/blob/master/xml/ns-Microsoft.Extensions.FileProviders.Physical.xml | https://review.docs.microsoft.com/en-us/dotnet/api/Microsoft.Extensions.FileProviders.Physical?branch=master Microsoft.Extensions.FileProviders.Composite namespace | Missing | NA | NA | NA | https://github.com/dotnet/dotnet-api-docs/blob/master/xml/ns-Microsoft.Extensions.FileProviders.Composite.xml | https://review.docs.microsoft.com/en-us/dotnet/api/Microsoft.Extensions.FileProviders.Composite?branch=master Microsoft.Extensions.FileProviders namespace | Missing | NA | NA | NA | https://github.com/dotnet/dotnet-api-docs/blob/master/xml/ns-Microsoft.Extensions.FileProviders.xml | https://review.docs.microsoft.com/en-us/dotnet/api/Microsoft.Extensions.FileProviders?branch=master M:Microsoft.Extensions.FileProviders.NullFileProvider.#ctor | Missing | NA | NA | NA | https://github.com/dotnet/dotnet-api-docs/blob/master/xml/Microsoft.Extensions.FileProviders/NullFileProvider.xml | https://review.docs.microsoft.com/en-us/dotnet/api/Microsoft.Extensions.FileProviders.NullFileProvider.-ctor?branch=master M:Microsoft.Extensions.FileProviders.NotFoundDirectoryContents.#ctor | Missing | NA | NA | NA | https://github.com/dotnet/dotnet-api-docs/blob/master/xml/Microsoft.Extensions.FileProviders/NotFoundDirectoryContents.xml | https://review.docs.microsoft.com/en-us/dotnet/api/Microsoft.Extensions.FileProviders.NotFoundDirectoryContents.-ctor?branch=master M:Microsoft.Extensions.FileProviders.FileSystemInfoHelper.#ctor | Missing | NA | NA | NA | https://github.com/dotnet/dotnet-api-docs/blob/master/xml/Microsoft.Extensions.FileProviders/FileSystemInfoHelper.xml | https://review.docs.microsoft.com/en-us/dotnet/api/Microsoft.Extensions.FileProviders.FileSystemInfoHelper.-ctor?branch=master

Notes:

• The namespaces need to be documented directly in dotnet-api-docs.
• Some of the APIs are obsolete, so I'll let area owners decide if they want to still document them or skip them. If you opt for documenting them, please do it directly in dotnet-api-docs.

[ghost]

Tagging subscribers to this area: @maryamariyan See info in area-owners.md if you want to be subscribed.

[TheMaximum]

I'm looking to add comments to the mentioned constructors, however at the moment they do not exist. I added them in https://github.com/TheMaximum/runtime/commit/f8fa633ef397f95a8f8bcd4ed62f47a6cead87c4, however I've got a few questions about it.

In my commit, I've created a private constructor for NotFoundDirectoryContents, as it is used as a Singleton. I couldn't find places where it is constructed except for the Singleton property in the class itself. Is this the right course of action, or should the class be allowed to be constructed elsewhere (bypassing the singleton), @maryamariyan?

https://github.com/dotnet/runtime/blob/a350bc6e0896d2869e4028fdafb94588e3fe0867/src/libraries/Microsoft.Extensions.FileProviders.Abstractions/src/NotFoundDirectoryContents.cs#L10-L18

Adding the constructor for NullFileProvider seems pretty straight-forward (?).

FileSystemInfoHelper is a static class and as such cannot have instance constructors, could you indicate why it shows up in the documentation and how to proceed, @carlossanlop?

[KalleOlaviNiemitalo]

The FileSystemInfoHelper doc page says it applies only to ".NET Platform Extensions 1.0, 1.1". The class is public and not static in the following, which I think is the 1.1 source code: https://github.com/aspnet/FileSystem/blob/rel/1.1.0/src/Microsoft.Extensions.FileProviders.Physical/FileSystemInfoHelper.cs

I guess these old branches aren't worth servicing for the sake of documenting a class that is not even public nowadays.

[TheMaximum]

I hadn't noticed it just being 1.0 and 1.1, I just looked into the code... thanks @KalleOlaviNiemitalo! Don't know if you want to add it in for the older version (and if so, where should that be done), @carlossanlop ?