Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

API documentation debt - Microsoft.Extensions.FileProvider #43900

Open
Tracked by #43849
carlossanlop opened this issue Oct 27, 2020 · 4 comments
Open
Tracked by #43849

API documentation debt - Microsoft.Extensions.FileProvider #43900

carlossanlop opened this issue Oct 27, 2020 · 4 comments
Labels
area-Extensions-FileSystem documentation Documentation bug or enhancement, does not impact product or test code help wanted [up-for-grabs] Good issue for external contributors
Milestone

Comments

@carlossanlop
Copy link
Member

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.
@carlossanlop carlossanlop added documentation Documentation bug or enhancement, does not impact product or test code help wanted [up-for-grabs] Good issue for external contributors untriaged New issue has not been triaged by the area owner area-Microsoft.Extensions labels Oct 27, 2020
@carlossanlop carlossanlop added this to the 6.0.0 milestone Oct 27, 2020
@ghost
Copy link

ghost commented Nov 5, 2020

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

@maryamariyan maryamariyan removed the untriaged New issue has not been triaged by the area owner label Nov 5, 2020
@TheMaximum
Copy link
Contributor

TheMaximum commented Feb 21, 2021

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?

/// <summary>
/// Represents a non-existing directory
/// </summary>
public class NotFoundDirectoryContents : IDirectoryContents
{
/// <summary>
/// A shared instance of <see cref="NotFoundDirectoryContents"/>
/// </summary>
public static NotFoundDirectoryContents Singleton { get; } = new NotFoundDirectoryContents();

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
Copy link

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
Copy link
Contributor

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 ?

@adamsitnik adamsitnik modified the milestones: 6.0.0, 7.0.0 Jul 28, 2021
@jeffhandley jeffhandley modified the milestones: 7.0.0, 8.0.0 Aug 10, 2022
@carlossanlop carlossanlop modified the milestones: 8.0.0, 9.0.0 Oct 11, 2023
@adamsitnik adamsitnik modified the milestones: 9.0.0, 10.0.0 Jul 17, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area-Extensions-FileSystem documentation Documentation bug or enhancement, does not impact product or test code help wanted [up-for-grabs] Good issue for external contributors
Projects
None yet
Development

No branches or pull requests

6 participants