8000 Restored enumeration member remarks #2 by rpetrusha · Pull Request #1637 · dotnet/dotnet-api-docs · GitHub
[go: up one dir, main page]
Skip to content

Restored enumeration member remarks #2 #1637

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.

Sign up for GitHub

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

Merged
merged 2 commits into from
Jan 18, 2019
Merged

Restored enumeration member remarks #2 #1637

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3102ab4
Restored enumeration member remarks #2
Jan 17, 2019
144b412
Addressed feedback
Jan 18, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 13 additions & 32 deletions xml/System.Globalization/CultureTypes.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,10 +44,22 @@

These culture type values are returned by the <xref:System.Globalization.CultureInfo.CultureTypes%2A?displayProperty=nameWithType> property, and also serve as a filter that limits the cultures returned by the <xref:System.Globalization.CultureInfo.GetCultures%2A?displayProperty=nameWithType> method. For more information on cultures, see <xref:System.Globalization.CultureInfo>.

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 `<languagecode2>-<country/regioncode2>`, where `<languagecode2>` is a lowercase two-letter code derived from ISO 639-1, and `<country/regioncode2>` 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 <xref:System.Globalization.CultureInfo.GetCultures%2A?displayProperty=nameWithType> method that specifies this value.

- **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 <xref:System.Globalization.CultureInfo.LCID%2A?displayProperty=nameWithType> 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 <xref:System.Globalization.CultureInfo.CultureTypes%2A> property.
Expand Down Expand Up @@ -201,17 +213,6 @@ On .NET Framework 4 and later versions and .NET Core running on Windows, it incl
<MemberValue>1</MemberValue>
<Docs>
<summary>Cultures that are associated with a language but are not specific to a country/region. </summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

The names of .NET cultures consist of the lowercase two-letter code derived from ISO 639-1. For example: "en" (English) is a neutral culture. Custom 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 <xref:System.Globalization.CultureInfo.GetCultures%2A?displayProperty=nameWithType> method that specifies this value.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="ReplacementCultures">
Expand Down Expand Up @@ -275,17 +276,6 @@ The names of .NET cultures consist of the lowercase two-letter code derived from
<MemberValue>2</MemberValue>
<Docs>
<summary>Cultures that are specific to a country/region. </summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

The names of these cultures follow RFC 4646 (Windows Vista and later). The format is "&lt;languagecode2&gt;-&lt;country/regioncode2&gt;", where &lt;languagecode2&gt; is a lowercase two-letter code derived from ISO 639-1 and &lt;country/regioncode2&gt; is an uppercase two-letter code derived from ISO 3166. For example, "en-US" for English (United States) is a specific culture.

Custom cultures (that is, cultures that are application- rather than system-defined) can have any user-specified name, not just a standard-compliant one.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="UserCustomCulture">
Expand Down Expand Up @@ -317,15 +307,6 @@ Custom cultures (that is, cultures that are application- rather than system-defi
<MemberValue>8</MemberValue>
<Docs>
<summary>**This member is deprecated.** Custom cultures created by the user.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

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 <xref:System.Globalization.CultureInfo.LCID%2A?displayProperty=nameWithType> 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.

]]></format>
</remarks>
</Docs>
</Member>
<Member MemberName="WindowsOnlyCultures">
Expand Down
30 changes: 3 additions & 27 deletions xml/System.Globalization/DateTimeStyles.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,15 +108,7 @@
</ReturnValue>
<MemberValue>16</MemberValue>
<Docs>
<summary>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 <see cref="F:System.Globalization.DateTimeStyles.AssumeLocal" />, 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 <see cref="F:System.Globalization.DateTimeStyles.AssumeUniversal" />, no conversion occurs. If the input string does not denote a local or UTC time, no conversion occurs and the resulting <see cref="P:System.DateTime.Kind" /> property is <see cref="F:System.DateTimeKind.Unspecified" />.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This value cannot be used with RoundtripKind.

]]></format>
</remarks>
<summary>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 <see cref="F:System.Globalization.DateTimeStyles.AssumeLocal" />, 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 <see cref="F:System.Globalization.DateTimeStyles.AssumeUniversal" />, no conversion occurs. If the input string does not denote a local or UTC time, no conversion occurs and the resulting <see cref="P:System.DateTime.Kind" /> property is <see cref="F:System.DateTimeKind.Unspecified" />. This value cannot be used with <see cref="F:System.Globalization.DateTimeStyles.RoundtripKind" />.</summary>
</Docs>
</Member>
<Member MemberName="AllowInnerWhite">
Expand Down Expand Up @@ -295,15 +287,7 @@
</ReturnValue>
<MemberValue>32</MemberValue>
<Docs>
<summary>If no time zone is specified in the parsed string, the string is assumed to denote a local time.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This value cannot be used with AssumeUniversal or RoundtripKind.

]]></format>
</remarks>
<summary>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 <see cref="F:System.Globalization.DateTimeStyles.AssumeUniversal" /> or <see cref="F:System.Globalization.DateTimeStyles.RoundtripKind" />.</summary>
</Docs>
</Member>
<Member MemberName="AssumeUniversal">
Expand Down Expand Up @@ -338,15 +322,7 @@
</ReturnValue>
<MemberValue>64</MemberValue>
<Docs>
<summary>If no time zone is specified in the parsed string, the string is assumed to denote a UTC.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
This value cannot be used with AssumeLocal or RoundtripKind.

]]></format>
</remarks>
<summary>If no time zone is specified in the parsed string, the string is assumed to denote a UTC. This value cannot be used with <see cref="F:System.Globalization.DateTimeStyles.AssumeLocal" /> or <see cref="F:System.Globalization.DateTimeStyles.RoundtripKind" />.</summary>
</Docs>
</Member>
<Member MemberName="NoCurrentDateDefault">
Expand Down
12 changes: 1 addition & 11 deletions xml/System.IO.Pipes/PipeAccessRights.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -413,17 +413,7 @@
</ReturnValue>
<MemberValue>1048576</MemberValue>
<Docs>
<summary>Specifies whether the application can wait for a pipe handle to synchronize with the completion of an I/O operation.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
The Synchronize 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.

]]></format>
</remarks>
<summary>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.</summary>
</Docs>
</Member>
<Member MemberName="TakeOwnership">
Expand Down
14 changes: 5 additions & 9 deletions xml/System.IO/FileOptions.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,10 @@
<summary>Represents advanced options for creating a <see cref="T:System.IO.FileStream" /> object.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks

Specifying the `FileOptions.SequentialScan` flag can increase performance for applications that read large files using sequential access. Performance gains can be even more noticeable for applications that read large files mostly sequentially, but occasionally skip over small ranges of bytes.

## Examples
The following example shows how to use the Asynchronous value when creating a file stream.
Expand Down Expand Up @@ -260,15 +264,7 @@
</ReturnValue>
<MemberValue>134217728</MemberValue>
<Docs>
<summary>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.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
Specifying this flag can increase performance for applications that read large files using sequential access. Performance gains can be even more noticeable for applications that read large files mostly sequentially, but occasionally skip over small ranges of bytes.

]]></format>
</remarks>
<summary>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. </summary>
</Docs>
</Member>
<Member MemberName="WriteThrough">
Expand Down
10 changes: 1 addition & 9 deletions xml/System.Reflection.Metadata/SignatureTypeCode.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -638,15 +638,7 @@
</ReturnValue>
<MemberValue>64</MemberValue>
<Docs>
<summary>Precedes a type <see cref="System.Reflection.Metadata.EntityHandle" /> in signatures.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
In raw metadata, this will be encoded as either ELEMENT_TYPE_CLASS (0x12) for reference types and 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.

]]></format>
</remarks>
<summary>Precedes a type <see cref="System.Reflection.Metadata.EntityHandle" /> 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.</summary>
</Docs>
</Member>
<Member MemberName="UInt16">
Expand Down
33 changes: 9 additions & 24 deletions xml/System.Reflection/BindingFlags.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <xref:System.Type> methods and other places such as <xref:System.Reflection.MethodBase.Invoke%2A?displayProperty=nameWithType> :
`BindingFlags` are used in the following <xref:System.Type> methods and other places such as <xref:System.Reflection.MethodBase.Invoke%2A?displayProperty=nameWithType>:

- <xref:System.Reflection.MethodBase.Invoke%2A?displayProperty=nameWithType>

Expand Down Expand Up @@ -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 <xref:System.Reflection.Binder.ChangeType%2A?displayProperty=nameWithType>. This table applies especially to the `ExactBinding` binding flag.
The following table lists the coercions performed by the default <xref:System.Reflection.Binder.ChangeType%2A?displayProperty=nameWithType>. This table applies especially to the `BindingFlags.ExactBinding` binding flag. The general principle is that <xref:System.Reflection.Binder.ChangeType%2A> 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|
|-----------------|-----------------|
Expand All @@ -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 <xref:System.Security.Permissions.ReflectionPermission>. 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.

Expand Down Expand Up @@ -312,19 +317,7 @@
</ReturnValue>
<MemberValue>65536</MemberValue>
<Docs>
<summary>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 <see langword="Binder" /> object, since that implies that the caller is supplying <see langword="BindToXXX" /> implementations that will pick the appropriate method.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
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 <xref:System.Security.Permissions.ReflectionPermission>. This is consistent with lookup of members that are protected, private, and so on.

The general principle is that <xref:System.Reflection.Binder.ChangeType%2A> 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.

]]></format>
</remarks>
<summary>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 <see langword="Binder" /> object, since that implies that the caller is supplying <see langword="BindToXXX" /> implementations that will pick the appropriate method. The default binder ignores this flag, while custom binders can implement the semantics of this flag.</summary>
</Docs>
</Member>
<Member MemberName="FlattenHierarchy">
Expand Down Expand Up @@ -679,15 +672,7 @@
</ReturnValue>
<MemberValue>262144</MemberValue>
<Docs>
<summary>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 <see cref="M:System.Type.InvokeMember(System.String,System.Reflection.BindingFlags,System.Reflection.Binder,System.Object,System.Object[],System.Reflection.ParameterModifier[],System.Globalization.CultureInfo,System.String[])" />.</summary>
<remarks>
<format type="text/markdown"><![CDATA[

## Remarks
Parameters with default values are used only in calls where trailing arguments are omitted. They must be the last arguments.

]]></format>
</remarks>
<summary>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 <see cref="M:System.Type.InvokeMember(System.String,System.Reflection.BindingFlags,System.Reflection.Binder,System.Object,System.Object[],System.Reflection.ParameterModifier[],System.Globalization.CultureInfo,System.String[])" />.<br/><br/>Parameters with default values are used only in calls where trailing arguments are omitted. They must be the last arguments.</summary>
</Docs>
</Member>
<Member MemberName="Public">
Expand Down
Loading
0