dotnet / dotnet/dotnet-api-docs

CultureInfo constructor / CreateSpecificCulture docs are misleading or incorrect

Open
#3,110 26 comments 1 reaction 0 assignees View on GitHub
area-System.Globalization Pri1 Pri3
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

**Issue description**

[`CultureInfo` constructor](https://docs.microsoft.com/en-us/dotnet/api/system.globalization.cultureinfo.-ctor?view=netframework-4.8#System_Globalization_CultureInfo__ctor_System_String_) and [`CultureInfo.CreateSpecificCulture()`](https://docs.microsoft.com/en-us/dotnet/api/system.globalization.cultureinfo.createspecificculture?view=netframework-4.8) documentation is highly misleading and confusing.

1. On both pages it states that the name parameter must be an existing culture, but it doesn't - it can be any well formed culture name, whether it exists or not.

2. The exceptions section for `CultureInfo.CreateSpecificCulture()` states that it throws `CultureNotFoundException` when:

> The culture specified by name does not have a specific culture associated with it.

I think it would be useful to note that in the docs this method returns a blank named `CultureInfo` object if the culture specified does not exist because that's rather counter-intuitive. Apparently it seems like sometimes the invariant culture behaves like a neutral culture and other times it doesn't (see https://github.com/dotnet/corefx/issues/40698#issuecomment-526785405)

3. It says this in the "note to callers" section of both pages:

> The .NET Framework 3.5 and earlier versions throw an ArgumentException if name is not a valid culture name. Starting with the .NET Framework 4, this method throws a CultureNotFoundException.

Why the heck was this changed? This seems like a terrible design decision. A badly formatted parameter should be throwing an argument exception, not an exception that indicates that it couldn't be found. The docs for `CultureNotFoundException` states:

> The exception that is thrown when a method attempts to construct a culture that is not available.

That's clearly not what is happening here. These methods will happily work fine with cultures that are not available as long as the name is well formed.

Regardless, seems that the docs should clarify this somewhat because the current behavior is highly unexpected.

4. It says this in the "note to callers" section of the `CultureInfo` constructor:

> Starting with apps that run under the .NET Framework 4 or later on Windows 7 or later, the method attempts to retrieve a CultureInfo object whose identifier is culture from the operating system; if the operating system does not support that culture, the method throws a CultureNotFoundException exception.

As stated above, it does not do this...it returns a `CultureInfo` object with the specified name which falls back to the invariant culture regardless of whether it exists in the OS or not .

**Target framework**

- [X] .NET Core
- [X] .NET Framework
- [X] .NET Standard

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.