dotnet / dotnet/dotnet-api-docs
Document SaveFileDialog.OpenFile() failure behvaior on various platforms.
- Dominant language
- C#
- Stars
- 949
- Forks
- 1.7k
- Avg merge
- 3d 27m
- Merged PRs (30d)
- 49
Description
On Mono, [any behavior which would result in an exception returns `null`](https://github.com/mono/mono/blob/4b5e2591eb299eb34d60b5217b14c1ad9f11e238/mcs/class/System.Windows.Forms/System.Windows.Forms/SaveFileDialog.cs#L88), making it [inconsistent with .netfx](https://github.com/mono/mono/issues/21455).
On [.netfx](https://referencesource.microsoft.com/#System.Windows.Forms/winforms/Managed/System/WinForms/SaveFileDialog.cs,66a104767467d192) and [.netcore](https://github.com/dotnet/winforms/blob/c402e2a21cc3d6ab1c3fe6209ff829361aa596b9/src/System.Windows.Forms/src/System/Windows/Forms/SaveFileDialog.cs#L77), it is a thin wrapper around `new FileStream()`, so any exception which that constructor throws may be thrown. A `null` reference cannot be returned.
The [existing documentation](https://docs.microsoft.com/en-us/dotnet/api/system.windows.forms.savefiledialog.openfile?view=netframework-2.0) has no discussion about how errors are handled. It should at least mention:
* If the dialog was not shown with a successful result prior to invocation, the method will throw `ArgumentNullException`.
* If the file cannot be opened (such as if a race condition results in the file being moved), one of the following may happen:
* `IOException` thrown (on .netfx/.netcore).
* `null` may be returned.
Contributor guide
Research direction
Start from the existing SaveFileDialog.OpenFile documentation linked in the issue and inspect the corresponding API documentation source in this repository. Document the behavior when the dialog was not successfully shown and when the file cannot be opened, including the platform-dependent exception or null result; done means the published entry clearly covers these cases.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- csharp
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 58/100