From 3102ab46eb3ca483445a47f7638fcdbc964e9c0c Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Thu, 17 Jan 2019 13:38:58 -0800 Subject: [PATCH 1/2] Restored enumeration member remarks #2 --- xml/System.Globalization/CultureTypes.xml | 45 ++++++------------- xml/System.Globalization/DateTimeStyles.xml | 30 ++----------- xml/System.IO.Pipes/PipeAccessRights.xml | 12 +---- xml/System.IO/FileOptions.xml | 14 +++--- .../SignatureTypeCode.xml | 10 +---- xml/System.Reflection/BindingFlags.xml | 33 ++++---------- .../CompilationRelaxations.xml | 10 +---- xml/System.Runtime/GCLatencyMode.xml | 38 +++------------- 8 files changed, 40 insertions(+), 152 deletions(-) diff --git a/xml/System.Globalization/CultureTypes.xml b/xml/System.Globalization/CultureTypes.xml index b894fe2733d..648e1eecaf3 100644 --- a/xml/System.Globalization/CultureTypes.xml +++ b/xml/System.Globalization/CultureTypes.xml @@ -44,10 +44,22 @@ These culture type values are returned by the property, and also serve as a filter that limits the cultures returned by the method. For more information on cultures, see . -Generally, your application should enumerate all cultures by using the `CultureTypes.AllCultures` value. This allows enumeration of custom cultures as well as the other culture types. +Generally, you enumerate all cultures by using the `CultureTypes.AllCultures` value. This allows enumeration of custom cultures as well as the other culture types. Note that all `CultureTypes` members have been deprecated except for `CultureTypes.AllCultures`, `CultureTypes.NeutralCultures`, and `CultureTypes.SpecificCultures`. + +.NET recognizes the following culture types, all of which are included in enumerations returned by the `CultureTypes.AllTypes` enumeration member: + +- **Specific cultures**, which specify a country/region and a language. The names of these cultures follow RFC 4646. The format is \-\", where \ is a lowercase two-letter code derived from ISO 639-1, and \ is an uppercase two-letter code derived from ISO 3166. For example, "en-US" for English (United States) is a specific culture. Custom specific cultures (that is, cultures that are application- rather than system-defined) can have any user-specified name, not just a standards-compliant one. + +- **Neutral cultures**, which specify a language without respect to a country/region. The names of neutral cultures consist of the lowercase two-letter code derived from ISO 639-1. For example: "en" (English) is a neutral culture. Custom neutral cultures (that is, cultures that are application- rather than system-defined) can have any user-specified name, not just a two-letter code. + The invariant culture is included in the array of cultures returned by the method that specifies this value. + +- Custom cultures. + + In Windows versions prior to Windows 10, the `UserCustomCulture` value is assigned to custom cultures created by the developer. In Windows 10, the `UserCustomCulture` value is also assigned to system cultures that are not backed by a complete set of cultural data and that do not have unique local identifiers. (All cultures of type `UserCustomCulture` share a value of `LOCALE_CUSTOM_UNSPECIFIED` (0x1000, or 4096)). As a result, the `CultureInfo.GetCultures(CultureTypes.UserCustomCulture)` method returns different sets of cultures on different Windows versions. + ## Examples The following example demonstrates the `CultureTypes.AllCultures` enumeration member and the property. @@ -201,17 +213,6 @@ On .NET Framework 4 and later versions and .NET Core running on Windows, it incl 1 Cultures that are associated with a language but are not specific to a country/region. - - method that specifies this value. - - ]]> - @@ -275,17 +276,6 @@ The names of .NET cultures consist of the lowercase two-letter code derived from 2 Cultures that are specific to a country/region. - - - @@ -317,15 +307,6 @@ Custom cultures (that is, cultures that are application- rather than system-defi 8 **This member is deprecated.** Custom cultures created by the user. - - value of `LOCALE_CUSTOM_UNSPECIFIED` (0x1000, or 4096)). As a result, the `CultureInfo.GetCultures(CultureTypes.UserCustomCulture)` method returns different sets of cultures on different Windows versions. - - ]]> - diff --git a/xml/System.Globalization/DateTimeStyles.xml b/xml/System.Globalization/DateTimeStyles.xml index 5f1a0c2ddd4..61b5f25a047 100644 --- a/xml/System.Globalization/DateTimeStyles.xml +++ b/xml/System.Globalization/DateTimeStyles.xml @@ -108,15 +108,7 @@ 16 - Date and time are returned as a Coordinated Universal Time (UTC). If the input string denotes a local time, through a time zone specifier or , the date and time are converted from the local time to UTC. If the input string denotes a UTC time, through a time zone specifier or , no conversion occurs. If the input string does not denote a local or UTC time, no conversion occurs and the resulting property is . - - - + Date and time are returned as a Coordinated Universal Time (UTC). If the input string denotes a local time, through a time zone specifier or , the date and time are converted from the local time to UTC. If the input string denotes a UTC time, through a time zone specifier or , no conversion occurs. If the input string does not denote a local or UTC time, no conversion occurs and the resulting property is . This value cannot be used with . @@ -295,15 +287,7 @@ 32 - If no time zone is specified in the parsed string, the string is assumed to denote a local time. - - - + If no time zone is specified in the parsed string, the string is assumed to denote a local time. This value cannot be used with or . @@ -338,15 +322,7 @@ 64 - If no time zone is specified in the parsed string, the string is assumed to denote a UTC. - - - + If no time zone is specified in the parsed string, the string is assumed to denote a UTC. This value cannot be used with or . diff --git a/xml/System.IO.Pipes/PipeAccessRights.xml b/xml/System.IO.Pipes/PipeAccessRights.xml index 5cc7cdf9f76..cce24337b71 100644 --- a/xml/System.IO.Pipes/PipeAccessRights.xml +++ b/xml/System.IO.Pipes/PipeAccessRights.xml @@ -413,17 +413,7 @@ 1048576 - Specifies whether the application can wait for a pipe handle to synchronize with the completion of an I/O operation. - - - + Specifies whether the application can wait for a pipe handle to synchronize with the completion of an I/O operation. This value is automatically set when allowing access to the pipe and automatically excluded when denying access to the pipe. The right to create a pipe requires this value. Note that if you do not explicitly set this value when you create a pipe, the value will be set automatically for you. diff --git a/xml/System.IO/FileOptions.xml b/xml/System.IO/FileOptions.xml index 1cdd8b3cfa3..3140114c2d2 100644 --- a/xml/System.IO/FileOptions.xml +++ b/xml/System.IO/FileOptions.xml @@ -42,6 +42,10 @@ Represents advanced options for creating a object. 134217728 - Indicates that the file is to be accessed sequentially from beginning to end. The system can use this as a hint to optimize file caching. If an application moves the file pointer for random access, optimum caching may not occur; however, correct operation is still guaranteed. - - - + Indicates that the file is to be accessed sequentially from beginning to end. The system can use this as a hint to optimize file caching. If an application moves the file pointer for random access, optimum caching may not occur; however, correct operation is still guaranteed. Specifying this flag can increase performance in some cases. diff --git a/xml/System.Reflection.Metadata/SignatureTypeCode.xml b/xml/System.Reflection.Metadata/SignatureTypeCode.xml index 0014660bf2b..a523b0b3afa 100644 --- a/xml/System.Reflection.Metadata/SignatureTypeCode.xml +++ b/xml/System.Reflection.Metadata/SignatureTypeCode.xml @@ -638,15 +638,7 @@ 64 - Precedes a type in signatures. - - - + Precedes a type in signatures. In raw metadata, this is encoded as either ELEMENT_TYPE_CLASS (0x12) for reference types or ELEMENT_TYPE_VALUETYPE (0x11) for value types. This is collapsed to a single code because Windows Runtime projections can project from class to value type or vice-versa, and the raw code is misleading in those cases. diff --git a/xml/System.Reflection/BindingFlags.xml b/xml/System.Reflection/BindingFlags.xml index 065a461bbcc..257e8b5172e 100644 --- a/xml/System.Reflection/BindingFlags.xml +++ b/xml/System.Reflection/BindingFlags.xml @@ -50,7 +50,7 @@ ## Remarks These `BindingFlags` control binding for a great many classes in the `System`, `System.Reflection`, and `System.Runtime` namespaces that invoke, create, get, set, and find members and types. - `BindingFlags` are used in the following methods and other places such as : + `BindingFlags` are used in the following methods and other places such as : - @@ -95,7 +95,7 @@ > [!NOTE] > You must specify `Instance` or `Static` along with `Public` or `NonPublic` or no members will be returned. - The following table lists the coercions performed by the default . This table applies especially to the `ExactBinding` binding flag. + The following table lists the coercions performed by the default . This table applies especially to the `BindingFlags.ExactBinding` binding flag. The general principle is that should perform only widening coercions, which never lose data. An example of a widening coercion is coercing a value that is a 32-bit signed integer to a value that is a 64-bit signed integer. This is distinguished from a narrowing coercion, which may lose data. An example of a narrowing coercion is coercing a 64-bit signed integer to a 32-bit signed integer. |Source Type|Target Type| |-----------------|-----------------| @@ -112,9 +112,14 @@ |`Int64`|`Single`, `Double`| |`Single`|`Double`| |Non-reference|By-reference.| + +When the `BindingFlags.ExactBinding` binding flag is used, reflection models the accessibility rules of the common type system. For example, if the caller is in the same assembly, the caller does not need special permissions for internal members. Otherwise, the caller needs . This is consistent with the lookup of members that are protected, private, and so on. + + + ## Examples The following example demonstrates many of the binding flags. @@ -312,19 +317,7 @@ 65536 - Specifies that types of the supplied arguments must exactly match the types of the corresponding formal parameters. Reflection throws an exception if the caller supplies a non-null object, since that implies that the caller is supplying implementations that will pick the appropriate method. - - . This is consistent with lookup of members that are protected, private, and so on. - - The general principle is that should perform only widening coercions, which never lose data. An example of a widening coercion is coercing a value that is a 32-bit signed integer to a value that is a 64-bit signed integer. This is distinguished from a narrowing coercion, which may lose data. An example of a narrowing coercion is coercing a 64-bit signed integer to a 32-bit signed integer. - - The default binder ignores this flag, while custom binders can implement the semantics of this flag. - - ]]> - + Specifies that types of the supplied arguments must exactly match the types of the corresponding formal parameters. Reflection throws an exception if the caller supplies a non-null object, since that implies that the caller is supplying implementations that will pick the appropriate method. The default binder ignores this flag, while custom binders can implement the semantics of this flag. @@ -679,15 +672,7 @@ 262144 - Returns the set of members whose parameter count matches the number of supplied arguments. This binding flag is used for methods with parameters that have default values and methods with variable arguments (varargs). This flag should only be used with . - - - + Returns the set of members whose parameter count matches the number of supplied arguments. This binding flag is used for methods with parameters that have default values and methods with variable arguments (varargs). This flag should only be used with .

Parameters with default values are used only in calls where trailing arguments are omitted. They must be the last arguments. diff --git a/xml/System.Runtime.CompilerServices/CompilationRelaxations.xml b/xml/System.Runtime.CompilerServices/CompilationRelaxations.xml index 53fa0a1d4a3..66893d335b3 100644 --- a/xml/System.Runtime.CompilerServices/CompilationRelaxations.xml +++ b/xml/System.Runtime.CompilerServices/CompilationRelaxations.xml @@ -74,15 +74,7 @@ 8 - Marks an assembly as not requiring string-literal interning. - - - + Marks an assembly as not requiring string-literal interning. In an application domain, the common language runtime creates one string object for each unique string literal, rather than making multiple copies. This behavior, called string interning, internally requires building auxiliary tables that consume memory resources. diff --git a/xml/System.Runtime/GCLatencyMode.xml b/xml/System.Runtime/GCLatencyMode.xml index 05a59252a69..f38f5c5f40a 100644 --- a/xml/System.Runtime/GCLatencyMode.xml +++ b/xml/System.Runtime/GCLatencyMode.xml @@ -38,10 +38,12 @@ property to any enumeration value except NoGCRegion. You can also determine the garbage collector's current latency mode by retrieving the property value. + You can adjust the intrusiveness of garbage collection in your application by setting the property to any enumeration value except `GCLatencyMode.NoGCRegion`. You can also determine the garbage collector's current latency mode by retrieving the property value. See [Latency Modes](~/docs/standard/garbage-collection/latency.md) for a discussion of how the runtime configuration settings for garbage collection affect the default value for this enumeration. - + +The mode overrides the [\](~/docs/framework/configure-apps/file-schema/runtime/gcconcurrent-element.md) runtime configuration setting. If concurrent garbage collection is enabled by the [\](~/docs/framework/configure-apps/file-schema/runtime/gcconcurrent-element.md) element, switching to Batch mode prevents any further concurrent collections. + ]]> Latency Modes @@ -79,17 +81,7 @@ 0 - Disables garbage collection concurrency and reclaims objects in a batch call. This is the most intrusive mode. - - - + Disables garbage collection concurrency and reclaims objects in a batch call. This is the most intrusive mode. This mode is designed for maximum throughput at the expense of responsiveness. @@ -124,15 +116,7 @@ 1 - Enables garbage collection concurrency and reclaims objects while the application is running. This is the default mode for garbage collection on a workstation and is less intrusive than . It balances responsiveness with throughput. - - - + Enables garbage collection concurrency and reclaims objects while the application is running. This is the default mode for garbage collection on a workstation and is less intrusive than . It balances responsiveness with throughput. This mode is equivalent to garbage collection on a workstation that is concurrent. @@ -167,15 +151,7 @@ 2 - Enables garbage collection that is more conservative in reclaiming objects. Full collections occur only if the system is under memory pressure, whereas generation 0 and generation 1 collections might occur more frequently - - - + Enables garbage collection that is more conservative in reclaiming objects. Full collections occur only if the system is under memory pressure, whereas generation 0 and generation 1 collections might occur more frequently. This mode is not available for the server garbage collector. From 144b412026556ba26a1a8167dc6a2eb5ea0d1e4e Mon Sep 17 00:00:00 2001 From: Ron Petrusha Date: Fri, 18 Jan 2019 08:50:32 -0800 Subject: [PATCH 2/2] Addressed feedback --- xml/System.Globalization/CultureTypes.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/xml/System.Globalization/CultureTypes.xml b/xml/System.Globalization/CultureTypes.xml index 648e1eecaf3..278459404a3 100644 --- a/xml/System.Globalization/CultureTypes.xml +++ b/xml/System.Globalization/CultureTypes.xml @@ -50,13 +50,13 @@ Note that all `CultureTypes` members have been deprecated except for `CultureTyp .NET recognizes the following culture types, all of which are included in enumerations returned by the `CultureTypes.AllTypes` enumeration member: -- **Specific cultures**, which specify a country/region and a language. The names of these cultures follow RFC 4646. The format is \-\", where \ is a lowercase two-letter code derived from ISO 639-1, and \ is an uppercase two-letter code derived from ISO 3166. For example, "en-US" for English (United States) is a specific culture. Custom specific cultures (that is, cultures that are application- rather than system-defined) can have any user-specified name, not just a standards-compliant one. +- **Specific cultures**, which specify a country/region and a language. The names of these cultures follow RFC 4646. The format is `-`, where `` is a lowercase two-letter code derived from ISO 639-1, and `` is an uppercase two-letter code derived from ISO 3166. For example, "en-US" for English (United States) is a specific culture. Custom specific cultures (that is, cultures that are application- rather than system-defined) can have any user-specified name, not just a standards-compliant one. - **Neutral cultures**, which specify a language without respect to a country/region. The names of neutral cultures consist of the lowercase two-letter code derived from ISO 639-1. For example: "en" (English) is a neutral culture. Custom neutral cultures (that is, cultures that are application- rather than system-defined) can have any user-specified name, not just a two-letter code. The invariant culture is included in the array of cultures returned by the method that specifies this value. -- Custom cultures. +- **Custom cultures**, which are application-defined cultures. Custom cultures can represent either specific cultures or neutral cultures and can have any application-specified name. In Windows versions prior to Windows 10, the `UserCustomCulture` value is assigned to custom cultures created by the developer. In Windows 10, the `UserCustomCulture` value is also assigned to system cultures that are not backed by a complete set of cultural data and that do not have unique local identifiers. (All cultures of type `UserCustomCulture` share a value of `LOCALE_CUSTOM_UNSPECIFIED` (0x1000, or 4096)). As a result, the `CultureInfo.GetCultures(CultureTypes.UserCustomCulture)` method returns different sets of cultures on different Windows versions.