From 2796ee6de00a0e57b4126a2f71f2d11b08bad311 Mon Sep 17 00:00:00 2001 From: Maryam Ariyan Date: Mon, 13 Apr 2020 17:05:51 -0700 Subject: [PATCH 1/2] Docs for Extensions: FileProviders and Hosting --- .../CompositeDirectoryContents.xml | 16 +++++++++---- .../EmbeddedResourceFileInfo.xml | 6 ++--- .../PhysicalDirectoryContents.xml | 23 +++++++++++++------ .../PhysicalDirectoryInfo.xml | 9 ++++---- .../PhysicalFileInfo.xml | 17 +++++++------- .../PollingWildCardChangeToken.xml | 15 ++++++------ .../ManifestEmbeddedFileProvider.xml | 20 ++++++++-------- .../NotFoundDirectoryContents.xml | 16 +++++++++---- .../NotFoundFileInfo.xml | 4 ++-- .../ConsoleLifetime.xml | 16 ++++++------- .../HostingEnvironment.xml | 10 ++++---- .../BackgroundService.xml | 4 ++-- .../ConfigurationChangeTokenSource`1.xml | 7 +++--- 13 files changed, 95 insertions(+), 68 deletions(-) diff --git a/xml/Microsoft.Extensions.FileProviders.Composite/CompositeDirectoryContents.xml b/xml/Microsoft.Extensions.FileProviders.Composite/CompositeDirectoryContents.xml index fd3726b14ba..5bb71c16053 100644 --- a/xml/Microsoft.Extensions.FileProviders.Composite/CompositeDirectoryContents.xml +++ b/xml/Microsoft.Extensions.FileProviders.Composite/CompositeDirectoryContents.xml @@ -1,4 +1,4 @@ - + @@ -153,9 +153,17 @@ - To be added. - To be added. - To be added. + Returns an enumerator that iterates through a collection. + An object that can be used to iterate through the collection. + + instance is cast to an interface. + + ]]> + diff --git a/xml/Microsoft.Extensions.FileProviders.Embedded/EmbeddedResourceFileInfo.xml b/xml/Microsoft.Extensions.FileProviders.Embedded/EmbeddedResourceFileInfo.xml index 63829e35223..3fee7eace87 100644 --- a/xml/Microsoft.Extensions.FileProviders.Embedded/EmbeddedResourceFileInfo.xml +++ b/xml/Microsoft.Extensions.FileProviders.Embedded/EmbeddedResourceFileInfo.xml @@ -1,4 +1,4 @@ - + @@ -87,8 +87,8 @@ - To be added. - To be added. + Return file contents as readonly stream. Caller should dispose stream when complete. + The file stream To be added. diff --git a/xml/Microsoft.Extensions.FileProviders.Internal/PhysicalDirectoryContents.xml b/xml/Microsoft.Extensions.FileProviders.Internal/PhysicalDirectoryContents.xml index a33c775d815..b98f531b093 100644 --- a/xml/Microsoft.Extensions.FileProviders.Internal/PhysicalDirectoryContents.xml +++ b/xml/Microsoft.Extensions.FileProviders.Internal/PhysicalDirectoryContents.xml @@ -1,4 +1,4 @@ - + @@ -109,7 +109,8 @@ System.Boolean - To be added. + + if a directory was located at the given path. To be added. To be added. @@ -140,8 +141,8 @@ - To be added. - To be added. + Returns an enumerator that iterates through the collection. + An enumerator that can be used to iterate through the collection. To be added. @@ -171,9 +172,17 @@ - To be added. - To be added. - To be added. + Returns an enumerator that iterates through a collection. + An object that can be used to iterate through the collection. + + instance is cast to an interface. + + ]]> + diff --git a/xml/Microsoft.Extensions.FileProviders.Physical/PhysicalDirectoryInfo.xml b/xml/Microsoft.Extensions.FileProviders.Physical/PhysicalDirectoryInfo.xml index d59b77882ad..810c7c8af15 100644 --- a/xml/Microsoft.Extensions.FileProviders.Physical/PhysicalDirectoryInfo.xml +++ b/xml/Microsoft.Extensions.FileProviders.Physical/PhysicalDirectoryInfo.xml @@ -1,4 +1,4 @@ - + @@ -112,7 +112,8 @@ System.Boolean - To be added. + + if resource exists in the underlying storage system. To be added. To be added. @@ -233,7 +234,7 @@ System.String - To be added. + The name of the file or directory, not including any path. To be added. To be added. @@ -264,7 +265,7 @@ System.String - To be added. + The path to the file, including the file name. Return if the file is not directly accessible. To be added. To be added. diff --git a/xml/Microsoft.Extensions.FileProviders.Physical/PhysicalFileInfo.xml b/xml/Microsoft.Extensions.FileProviders.Physical/PhysicalFileInfo.xml index f30c08eed6f..764792e2649 100644 --- a/xml/Microsoft.Extensions.FileProviders.Physical/PhysicalFileInfo.xml +++ b/xml/Microsoft.Extensions.FileProviders.Physical/PhysicalFileInfo.xml @@ -1,4 +1,4 @@ - + @@ -81,8 +81,8 @@ - To be added. - To be added. + Return file contents as readonly stream. Caller should dispose stream when complete. + The file stream To be added. @@ -112,7 +112,8 @@ System.Boolean - To be added. + + if resource exists in the underlying storage system. To be added. To be added. @@ -173,7 +174,7 @@ System.DateTimeOffset - To be added. + Gets when the file was last modified. To be added. To be added. @@ -204,7 +205,7 @@ System.Int64 - To be added. + The length of the file in bytes, or -1 for a directory or non-existing files. To be added. To be added. @@ -235,7 +236,7 @@ System.String - To be added. + The name of the file or directory, not including any path. To be added. To be added. @@ -266,7 +267,7 @@ System.String - To be added. + The path to the file, including the file name. Return if the file is not directly accessible. To be added. To be added. diff --git a/xml/Microsoft.Extensions.FileProviders.Physical/PollingWildCardChangeToken.xml b/xml/Microsoft.Extensions.FileProviders.Physical/PollingWildCardChangeToken.xml index 928810e3380..381ddb4f9f3 100644 --- a/xml/Microsoft.Extensions.FileProviders.Physical/PollingWildCardChangeToken.xml +++ b/xml/Microsoft.Extensions.FileProviders.Physical/PollingWildCardChangeToken.xml @@ -1,4 +1,4 @@ - + @@ -79,7 +79,7 @@ System.Boolean - To be added. + Indicates if this token will pro-actively raise callbacks. If , the token consumer must poll to detect changes. To be added. To be added. @@ -139,7 +139,7 @@ System.Boolean - To be added. + Gets a value that indicates if a change has occurred. To be added. To be added. @@ -173,10 +173,11 @@ - To be added. - To be added. - To be added. - To be added. + The to invoke. + State to be passed into the callback. + Registers for a callback that will be invoked when the entry has changed. + MUST be set before the callback is invoked. + An that is used to unregister the callback. To be added. diff --git a/xml/Microsoft.Extensions.FileProviders/ManifestEmbeddedFileProvider.xml b/xml/Microsoft.Extensions.FileProviders/ManifestEmbeddedFileProvider.xml index 8b0f89d9d04..26dc41fd22e 100644 --- a/xml/Microsoft.Extensions.FileProviders/ManifestEmbeddedFileProvider.xml +++ b/xml/Microsoft.Extensions.FileProviders/ManifestEmbeddedFileProvider.xml @@ -1,4 +1,4 @@ - + @@ -186,9 +186,9 @@ - To be added. - To be added. - To be added. + Relative path that identifies the directory. + Enumerate a directory at the given path, if any. + Returns the contents of the directory. To be added. @@ -218,9 +218,9 @@ - To be added. - To be added. - To be added. + Relative path that identifies the file. + Locate a file at the given path. + The file information. Caller must check Exists property. To be added. @@ -250,9 +250,9 @@ - To be added. - To be added. - To be added. + Filter string used to determine what files or folders to monitor. Example: **/*.cs, *.*, subFolder/**/*.cshtml. + Creates a for the specified . + An that is notified when a file matching is added, modified or deleted. To be added. diff --git a/xml/Microsoft.Extensions.FileProviders/NotFoundDirectoryContents.xml b/xml/Microsoft.Extensions.FileProviders/NotFoundDirectoryContents.xml index 591bfc1f2f0..8ed2fc83f5c 100644 --- a/xml/Microsoft.Extensions.FileProviders/NotFoundDirectoryContents.xml +++ b/xml/Microsoft.Extensions.FileProviders/NotFoundDirectoryContents.xml @@ -1,4 +1,4 @@ - + @@ -170,9 +170,17 @@ - To be added. - To be added. - To be added. + Returns an enumerator that iterates through a collection. + An object that can be used to iterate through the collection. + + instance is cast to an interface. + + ]]> + diff --git a/xml/Microsoft.Extensions.FileProviders/NotFoundFileInfo.xml b/xml/Microsoft.Extensions.FileProviders/NotFoundFileInfo.xml index 10f5a07c21f..729715ed2b3 100644 --- a/xml/Microsoft.Extensions.FileProviders/NotFoundFileInfo.xml +++ b/xml/Microsoft.Extensions.FileProviders/NotFoundFileInfo.xml @@ -1,4 +1,4 @@ - + @@ -232,7 +232,7 @@ System.String - To be added. + The name of the file or directory, not including any path. To be added. To be added. diff --git a/xml/Microsoft.Extensions.Hosting.Internal/ConsoleLifetime.xml b/xml/Microsoft.Extensions.Hosting.Internal/ConsoleLifetime.xml index ef0e2da04d8..ebc51233d91 100644 --- a/xml/Microsoft.Extensions.Hosting.Internal/ConsoleLifetime.xml +++ b/xml/Microsoft.Extensions.Hosting.Internal/ConsoleLifetime.xml @@ -1,4 +1,4 @@ - + @@ -135,7 +135,7 @@ - To be added. + Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. To be added. @@ -164,9 +164,9 @@ - To be added. - To be added. - To be added. + Used to indicate when stop should no longer be graceful. + Called from to indicate that the host is stopping and it's time to shut down. + A . To be added. @@ -195,9 +195,9 @@ - To be added. - To be added. - To be added. + Used to indicate when stop should no longer be graceful. + Called at the start of which will wait until it's complete before continuing. This can be used to delay startup until signaled by an external event. + A . To be added. diff --git a/xml/Microsoft.Extensions.Hosting.Internal/HostingEnvironment.xml b/xml/Microsoft.Extensions.Hosting.Internal/HostingEnvironment.xml index ac7fa76581b..97cedc2da7d 100644 --- a/xml/Microsoft.Extensions.Hosting.Internal/HostingEnvironment.xml +++ b/xml/Microsoft.Extensions.Hosting.Internal/HostingEnvironment.xml @@ -1,4 +1,4 @@ - + @@ -78,7 +78,7 @@ System.String - To be added. + Gets or sets the name of the application. This property is automatically set by the host to the assembly containing the application entry point. To be added. To be added. @@ -106,7 +106,7 @@ Microsoft.Extensions.FileProviders.IFileProvider - To be added. + Gets or sets an pointing at . To be added. To be added. @@ -134,7 +134,7 @@ System.String - To be added. + Gets or sets the absolute path to the directory that contains the application content files. To be added. To be added. @@ -162,7 +162,7 @@ System.String - To be added. + Gets or sets the name of the environment. The host automatically sets this property to the value of the of the "environment" key as specified in configuration. To be added. To be added. diff --git a/xml/Microsoft.Extensions.Hosting/BackgroundService.xml b/xml/Microsoft.Extensions.Hosting/BackgroundService.xml index 4a066a12e6a..661297bf97e 100644 --- a/xml/Microsoft.Extensions.Hosting/BackgroundService.xml +++ b/xml/Microsoft.Extensions.Hosting/BackgroundService.xml @@ -1,4 +1,4 @@ - + @@ -71,7 +71,7 @@ - To be added. + Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. To be added. diff --git a/xml/Microsoft.Extensions.Options/ConfigurationChangeTokenSource`1.xml b/xml/Microsoft.Extensions.Options/ConfigurationChangeTokenSource`1.xml index 8661df4c9c1..3ceb0e5536c 100644 --- a/xml/Microsoft.Extensions.Options/ConfigurationChangeTokenSource`1.xml +++ b/xml/Microsoft.Extensions.Options/ConfigurationChangeTokenSource`1.xml @@ -1,4 +1,4 @@ - + @@ -26,8 +26,7 @@ - - + Creates s so that gets notified when changes. To be added. @@ -112,7 +111,7 @@ Returns the reloadToken from the . - + Change token. To be added. From f836fab1611292e773ff2e7e94240d992e42b9a8 Mon Sep 17 00:00:00 2001 From: Maryam Ariyan Date: Wed, 2 Sep 2020 13:29:13 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Applied PR feedback. Co-authored-by: Carlos Sanchez <1175054+carlossanlop@users.noreply.github.com> --- .../CompositeDirectoryContents.xml | 2 +- .../EmbeddedResourceFileInfo.xml | 14 +++++++++--- .../PhysicalDirectoryContents.xml | 7 +++--- .../PhysicalDirectoryInfo.xml | 13 +++++------ .../PhysicalFileInfo.xml | 22 ++++++++++++------- 5 files changed, 35 insertions(+), 23 deletions(-) diff --git a/xml/Microsoft.Extensions.FileProviders.Composite/CompositeDirectoryContents.xml b/xml/Microsoft.Extensions.FileProviders.Composite/CompositeDirectoryContents.xml index 5bb71c16053..9a6cf5c6838 100644 --- a/xml/Microsoft.Extensions.FileProviders.Composite/CompositeDirectoryContents.xml +++ b/xml/Microsoft.Extensions.FileProviders.Composite/CompositeDirectoryContents.xml @@ -154,7 +154,7 @@ Returns an enumerator that iterates through a collection. - An object that can be used to iterate through the collection. + An enumerator that can be used to iterate through the collection. - Return file contents as readonly stream. Caller should dispose stream when complete. - The file stream - To be added. + Returns the file contents as a read-only stream. + A read-only stream. + + + diff --git a/xml/Microsoft.Extensions.FileProviders.Internal/PhysicalDirectoryContents.xml b/xml/Microsoft.Extensions.FileProviders.Internal/PhysicalDirectoryContents.xml index b98f531b093..207cb027cfe 100644 --- a/xml/Microsoft.Extensions.FileProviders.Internal/PhysicalDirectoryContents.xml +++ b/xml/Microsoft.Extensions.FileProviders.Internal/PhysicalDirectoryContents.xml @@ -109,9 +109,8 @@ System.Boolean - - if a directory was located at the given path. - To be added. + Determines if a directory was located at the given path. + if a directory was located at the given path; otherwise. To be added. @@ -173,7 +172,7 @@ Returns an enumerator that iterates through a collection. - An object that can be used to iterate through the collection. + An enumerator that can be used to iterate through the collection. System.Boolean - - if resource exists in the underlying storage system. - To be added. + Determines if the resource exists in the underlying storage system. + if the resource exists in the underlying storage system; otherwise. To be added. @@ -234,8 +233,8 @@ System.String - The name of the file or directory, not including any path. - To be added. + Gets the name of the file or directory, excluding the path. + A string representing the name of the file or directory. To be added. @@ -265,8 +264,8 @@ System.String - The path to the file, including the file name. Return if the file is not directly accessible. - To be added. + Gets the full path to the file, including the file name. + A string representing the full path to the file, or if the file is not directly accessible. To be added. diff --git a/xml/Microsoft.Extensions.FileProviders.Physical/PhysicalFileInfo.xml b/xml/Microsoft.Extensions.FileProviders.Physical/PhysicalFileInfo.xml index 764792e2649..a96f816fac4 100644 --- a/xml/Microsoft.Extensions.FileProviders.Physical/PhysicalFileInfo.xml +++ b/xml/Microsoft.Extensions.FileProviders.Physical/PhysicalFileInfo.xml @@ -81,9 +81,16 @@ - Return file contents as readonly stream. Caller should dispose stream when complete. - The file stream - To be added. + Returns the file contents as a read-only stream. + A read-only stream. + + + @@ -112,9 +119,8 @@ System.Boolean - - if resource exists in the underlying storage system. - To be added. + Determines if the resource exists in the underlying system. + if the resource exists in the underlying storage system; otherwise. To be added. @@ -174,8 +180,8 @@ System.DateTimeOffset - Gets when the file was last modified. - To be added. + Gets the last time the file was modified. + A datetime offset representing the last time the file was modified. To be added.