From f32b67639eac3a526c029731f7e0edf649df6c8c Mon Sep 17 00:00:00 2001 From: carlossanlop Date: Fri, 3 Sep 2021 01:07:25 -0700 Subject: [PATCH 1/2] Port System.Reflection triple slash to docs --- .../MetadataUpdateHandlerAttribute.xml | 31 +++++++++++++++--- .../MetadataUpdater.xml | 29 +++++++++++++---- xml/System.Reflection/NullabilityInfo.xml | 12 +++---- .../NullabilityInfoContext.xml | 32 +++++++++++-------- xml/System.Reflection/NullabilityState.xml | 8 ++--- 5 files changed, 76 insertions(+), 36 deletions(-) diff --git a/xml/System.Reflection.Metadata/MetadataUpdateHandlerAttribute.xml b/xml/System.Reflection.Metadata/MetadataUpdateHandlerAttribute.xml index bc0a934528a..01d24f0ea16 100644 --- a/xml/System.Reflection.Metadata/MetadataUpdateHandlerAttribute.xml +++ b/xml/System.Reflection.Metadata/MetadataUpdateHandlerAttribute.xml @@ -20,8 +20,29 @@ - To be added. - To be added. + Specifies a type that should receive notifications of metadata updates. + + specified by this attribute should implement static methods matching the signature of one or more + of the following (visibility of the methods does not matter): + `static void ClearCache(Type[]? updatedTypes)``static void UpdateApplication(Type[]? updatedTypes)` + + + After a metadata update is applied, `ClearCache` is invoked for every handler that specifies one. This gives update handlers + an opportunity to clear any caches that are inferred based on the application's metadata. After all `ClearCache` methods + have been invoked, `UpdateApplication` is invoked for every handler that specifies one. This enables applications to refresh + application state, trigger a UI re-render, or other such reactions. When specified, the `updatedTypes` parameter contains the + set of types that were affected by the metadata update; if it's `null`, any type may have been updated. + + + + + ]]> + @@ -47,8 +68,8 @@ - To be added. - To be added. + A type that handles metadata updates and that should be notified when any occur. + Initializes the attribute. To be added. @@ -74,7 +95,7 @@ System.Type - To be added. + Gets the type that handles metadata updates and that should be notified when any occur. To be added. To be added. diff --git a/xml/System.Reflection.Metadata/MetadataUpdater.xml b/xml/System.Reflection.Metadata/MetadataUpdater.xml index 0a83755e1b8..d17e6d6dbe9 100644 --- a/xml/System.Reflection.Metadata/MetadataUpdater.xml +++ b/xml/System.Reflection.Metadata/MetadataUpdater.xml @@ -40,12 +40,27 @@ - To be added. - To be added. - To be added. - To be added. - To be added. - To be added. + The assembly to update. + The metadata changes to be applied. + The IL changes to be applied. + The PDB changes to be applied. + Updates the specified assembly using the provided metadata, IL and PDB deltas. + + + + The assembly argument is not a runtime assembly. + The assembly argument is . + The assembly is not editable. + The update could not be applied. @@ -64,7 +79,7 @@ System.Boolean - To be added. + Returns if the apply assembly update is enabled and available; otherwise. To be added. To be added. diff --git a/xml/System.Reflection/NullabilityInfo.xml b/xml/System.Reflection/NullabilityInfo.xml index 280366e2ebb..7a17db96aa1 100644 --- a/xml/System.Reflection/NullabilityInfo.xml +++ b/xml/System.Reflection/NullabilityInfo.xml @@ -14,7 +14,7 @@ - To be added. + A class that represents nullability information. To be added. @@ -34,7 +34,7 @@ System.Reflection.NullabilityInfo - To be added. + If the member type is an array, gives the of the elements of the array, otherwise. To be added. To be added. @@ -55,7 +55,7 @@ System.Reflection.NullabilityInfo[] - To be added. + If the member type is a generic type, gives the array of for each type parameter. To be added. To be added. @@ -76,7 +76,7 @@ System.Reflection.NullabilityState - To be added. + The nullability read state of the member. To be added. To be added. @@ -97,7 +97,7 @@ System.Type - To be added. + The of the member or generic parameter to which this instance belongs. To be added. To be added. @@ -118,7 +118,7 @@ System.Reflection.NullabilityState - To be added. + The nullability write state of the member. To be added. To be added. diff --git a/xml/System.Reflection/NullabilityInfoContext.xml b/xml/System.Reflection/NullabilityInfoContext.xml index bdbefb1fb1d..16186b0f257 100644 --- a/xml/System.Reflection/NullabilityInfoContext.xml +++ b/xml/System.Reflection/NullabilityInfoContext.xml @@ -14,7 +14,7 @@ - To be added. + Provides APIs for populating nullability information/context from reflection members: , , and . To be added. @@ -31,7 +31,7 @@ - To be added. + Creates a instance. To be added. @@ -54,10 +54,11 @@ - To be added. - To be added. - To be added. + The event for which the nullability information gets populated. + Populates a for the given . If the nullablePublicOnly feature is set for an assembly, like it does in the .NET SDK, the private and/or internal member's nullability attributes are omitted, and the API will return the state. + A instance. To be added. + is . @@ -79,10 +80,11 @@ - To be added. - To be added. - To be added. + The field for which the nullability information gets populated. + Populates a for the given . If the nullablePublicOnly feature is set for an assembly, like it does in the .NET SDK, the private and/or internal member's nullability attributes are omitted, and the API will return the state. + A instance. To be added. + is . @@ -104,10 +106,11 @@ - To be added. - To be added. - To be added. + The parameter for which the nullability information gets populated. + Populates a for the given . If the nullablePublicOnly feature is set for an assembly, like it does in the .NET SDK, the private and/or internal member's nullability attributes are omitted, and the API will return the state. + A instance. To be added. + is . @@ -129,10 +132,11 @@ - To be added. - To be added. - To be added. + The property for which the nullability information gets populated. + Populates a for the given . If the nullablePublicOnly feature is set for an assembly, like it does in the .NET SDK, the private and/or internal member's nullability attributes are omitted, and the API will return the state. + A instance. To be added. + is . diff --git a/xml/System.Reflection/NullabilityState.xml b/xml/System.Reflection/NullabilityState.xml index 7da1d89c239..7f7491f91fc 100644 --- a/xml/System.Reflection/NullabilityState.xml +++ b/xml/System.Reflection/NullabilityState.xml @@ -13,7 +13,7 @@ System.Enum - To be added. + An enumeration that describes nullability state. To be added. @@ -34,7 +34,7 @@ 1 - To be added. + Non-nullable value or reference type. @@ -54,7 +54,7 @@ 2 - To be added. + Nullable value or reference type. @@ -74,7 +74,7 @@ 0 - To be added. + Nullability context not enabled (oblivious). From b18a90221a4b5bc49927bd409486351a69974f0f Mon Sep 17 00:00:00 2001 From: Carlos Sanchez <1175054+carlossanlop@users.noreply.github.com> Date: Wed, 8 Sep 2021 12:42:03 -0700 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> Co-authored-by: Buyaa Namnan --- .../MetadataUpdateHandlerAttribute.xml | 19 ++++----------- .../MetadataUpdater.xml | 11 ++++----- xml/System.Reflection/NullabilityInfo.xml | 16 ++++++------- .../NullabilityInfoContext.xml | 24 +++++++++++-------- xml/System.Reflection/NullabilityState.xml | 2 +- 5 files changed, 32 insertions(+), 40 deletions(-) diff --git a/xml/System.Reflection.Metadata/MetadataUpdateHandlerAttribute.xml b/xml/System.Reflection.Metadata/MetadataUpdateHandlerAttribute.xml index 01d24f0ea16..9e27664faac 100644 --- a/xml/System.Reflection.Metadata/MetadataUpdateHandlerAttribute.xml +++ b/xml/System.Reflection.Metadata/MetadataUpdateHandlerAttribute.xml @@ -20,26 +20,17 @@ - Specifies a type that should receive notifications of metadata updates. + Indicates that a type that should receive notifications of metadata updates. specified by this attribute should implement static methods matching the signature of one or more of the following (visibility of the methods does not matter): + - `static void ClearCache(Type[]? updatedTypes)` + - `static void UpdateApplication(Type[]? updatedTypes)` - The specified by this attribute should implement static methods matching the signature of one or more - of the following (visibility of the methods does not matter): - `static void ClearCache(Type[]? updatedTypes)``static void UpdateApplication(Type[]? updatedTypes)` - - - After a metadata update is applied, `ClearCache` is invoked for every handler that specifies one. This gives update handlers - an opportunity to clear any caches that are inferred based on the application's metadata. After all `ClearCache` methods - have been invoked, `UpdateApplication` is invoked for every handler that specifies one. This enables applications to refresh - application state, trigger a UI re-render, or other such reactions. When specified, the `updatedTypes` parameter contains the - set of types that were affected by the metadata update; if it's `null`, any type may have been updated. - - - +After a metadata update is applied, `ClearCache` is invoked for every handler that specifies one. This gives update handlers an opportunity to clear any caches that are inferred based on the application's metadata. After all `ClearCache` methods have been invoked, `UpdateApplication` is invoked for every handler that specifies one. This enables applications to refresh the application state, trigger a UI re-render, or other such reactions. When specified, the `updatedTypes` parameter contains the set of types that were affected by the metadata update; if it's `null`, any type may have been updated. ]]> diff --git a/xml/System.Reflection.Metadata/MetadataUpdater.xml b/xml/System.Reflection.Metadata/MetadataUpdater.xml index d17e6d6dbe9..73547ecd942 100644 --- a/xml/System.Reflection.Metadata/MetadataUpdater.xml +++ b/xml/System.Reflection.Metadata/MetadataUpdater.xml @@ -44,16 +44,13 @@ The metadata changes to be applied. The IL changes to be applied. The PDB changes to be applied. - Updates the specified assembly using the provided metadata, IL and PDB deltas. + Updates the specified assembly using the provided metadata, IL, and PDB deltas. @@ -79,8 +76,8 @@ Currently executing methods will continue to use the existing IL. New executions System.Boolean - Returns if the apply assembly update is enabled and available; otherwise. - To be added. + Gets a value that indicates whether the assembly update is enabled and available. + if the assembly update is enabled and available; otherwise, . To be added. diff --git a/xml/System.Reflection/NullabilityInfo.xml b/xml/System.Reflection/NullabilityInfo.xml index 7a17db96aa1..8558d480923 100644 --- a/xml/System.Reflection/NullabilityInfo.xml +++ b/xml/System.Reflection/NullabilityInfo.xml @@ -14,7 +14,7 @@ - A class that represents nullability information. + Represents nullability information. To be added. @@ -34,8 +34,8 @@ System.Reflection.NullabilityInfo - If the member type is an array, gives the of the elements of the array, otherwise. - To be added. + Gets the nullability information for the element type of the array. + If the member type is an array, the of the elements of the array; otherwise, . To be added. @@ -55,8 +55,8 @@ System.Reflection.NullabilityInfo[] - If the member type is a generic type, gives the array of for each type parameter. - To be added. + Gets the nullability information for each type parameter. + If the member type is a generic type, the nullability information for each type parameter. To be added. @@ -76,7 +76,7 @@ System.Reflection.NullabilityState - The nullability read state of the member. + Gets the nullability read state of the member. To be added. To be added. @@ -97,7 +97,7 @@ System.Type - The of the member or generic parameter to which this instance belongs. + Gets the type of the member or generic parameter to which this instance belongs. To be added. To be added. @@ -118,7 +118,7 @@ System.Reflection.NullabilityState - The nullability write state of the member. + Gets the nullability write state of the member. To be added. To be added. diff --git a/xml/System.Reflection/NullabilityInfoContext.xml b/xml/System.Reflection/NullabilityInfoContext.xml index 16186b0f257..b885f993b95 100644 --- a/xml/System.Reflection/NullabilityInfoContext.xml +++ b/xml/System.Reflection/NullabilityInfoContext.xml @@ -14,7 +14,7 @@ - Provides APIs for populating nullability information/context from reflection members: , , and . + Provides APIs for populating nullability information and context from reflection members: , , , and . To be added. @@ -31,7 +31,7 @@ - Creates a instance. + Initializes a new instance of the class. To be added. @@ -54,11 +54,12 @@ - The event for which the nullability information gets populated. + The event for which to populate nullability information. Populates a for the given . If the nullablePublicOnly feature is set for an assembly, like it does in the .NET SDK, the private and/or internal member's nullability attributes are omitted, and the API will return the state. A instance. To be added. - is . + + is . @@ -80,11 +81,12 @@ - The field for which the nullability information gets populated. + The field for which to populate the nullability information. Populates a for the given . If the nullablePublicOnly feature is set for an assembly, like it does in the .NET SDK, the private and/or internal member's nullability attributes are omitted, and the API will return the state. A instance. To be added. - is . + + is . @@ -106,11 +108,12 @@ - The parameter for which the nullability information gets populated. + The parameter for which to populate the nullability information. Populates a for the given . If the nullablePublicOnly feature is set for an assembly, like it does in the .NET SDK, the private and/or internal member's nullability attributes are omitted, and the API will return the state. A instance. To be added. - is . + + is . @@ -132,11 +135,12 @@ - The property for which the nullability information gets populated. + The property for which to populate the nullability information. Populates a for the given . If the nullablePublicOnly feature is set for an assembly, like it does in the .NET SDK, the private and/or internal member's nullability attributes are omitted, and the API will return the state. A instance. To be added. - is . + + is . diff --git a/xml/System.Reflection/NullabilityState.xml b/xml/System.Reflection/NullabilityState.xml index 7f7491f91fc..83a1e9bcde1 100644 --- a/xml/System.Reflection/NullabilityState.xml +++ b/xml/System.Reflection/NullabilityState.xml @@ -13,7 +13,7 @@ System.Enum - An enumeration that describes nullability state. + Describes nullability states. To be added.