dotnet / dotnet/dotnet-api-docs

Improve `System.FormatException` docs

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

Description

### Type of issue

Missing information

### Description

According to the current `FormatException` docs:

> The exception that is thrown when the format of an argument is invalid, or when a [composite format string](https://learn.microsoft.com/en-us/dotnet/standard/base-types/composite-formatting) is not well formed.

However, as described in this [StackOverflow post](https://stackoverflow.com/questions/2135328/why-does-formatexception-not-inherit-from-argumentexception):

> `FormatException` is not necessarily thrown when a formal argument of a method is invalid. It can also happen if the method is consuming an external resource and the format of the data from the external resource is inappropriate.

> For example, [`BinaryReader.Read7BitEncodedInt`](http://msdn.microsoft.com/en-us/library/system.io.binaryreader.read7bitencodedint.aspx) will throw `FormatException` if what it's going to read from a stream is not a valid 7-bit encoded integer. It doesn't take any arguments at all. `ArgumentException`, on the other hand, should only get thrown when an argument passed as a formal parameter to a method is invalid.

The docs should be updated to clarify this. I'd be willing to try a PR if someone wants to point me to the right files.

### Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.formatexception?view=net-8.0&redirectedfrom=MSDN

### Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System/FormatException.xml

### Document Version Independent Id

691e8234-8211-094f-f6d7-b22ed063cfc5

### Article author

@dotnet-bot

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.