-
Notifications
You must be signed in to change notification settings - Fork 5.3k
Add missing System.Formats.Tar docs #74786
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.
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
Conversation
|
Tagging subscribers to this area: @dotnet/area-system-io Issue Detailsnull
|
src/libraries/System.Formats.Tar/src/System/Formats/Tar/TarReader.cs
Outdated
Show resolved
Hide resolved
src/libraries/System.Formats.Tar/src/System/Formats/Tar/UstarTarEntry.cs
Outdated
Show resolved
Hide resolved
src/libraries/System.Formats.Tar/src/System/Formats/Tar/V7TarEntry.cs
Outdated
Show resolved
Hide resolved
src/libraries/System.Formats.Tar/src/System/Formats/Tar/PaxTarEntry.cs
Outdated
Show resolved
Hide resolved
src/libraries/System.Formats.Tar/src/System/Formats/Tar/GnuTarEntry.cs
Outdated
Show resolved
Hide resolved
Co-authored-by: Dan Moseley <[email protected]>
| /// Initializes a new <see cref="GnuTarEntry"/> instance by converting the specified <paramref name="other"/> entry into the GNU format. | ||
| /// </summary> | ||
| /// <param name="other">The <see cref="TarEntry"/> instance to convert to the GNU format.</param> | ||
| /// <exception cref="InvalidOperationException"><para><paramref name="other"/> is a <see cref="PaxGlobalExtendedAttributesTarEntry"/> instance.</para> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Shouldn't this be ArgumentException? InvalidOperationException conveys a state error.
The exception that is thrown when a method call is invalid for the object's current state.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's what TarHelpers throws in the base.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It is not possible to convert a PAX GEA entry to any other type. So your code is in an invalid state at this point for attempting that.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It's the object's current state, not the code's. There's no object until the ctor returns, I think it is even wrong to throw InvalidOperation in a ctor.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
cc @bartonjs as we recently discussed similar cases.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm wondering: if we change the exception type, it wouldn't meet the 7.0 servicing bar and if we change it on 8.0, it would imply a breaking change (which may not be worth it?). So this is not actionable until proven otherwise (customer feedback, etc.).
cc @danmoseley, is my reasoning correct?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@jozkee is correct, in new code this should be an ArgumentException because
- Your exception text blames the cause of the exception on a parameter/argument, and
- It's easy enough for the caller to have known it was going to throw.
InvalidOperationException means "you asked an object to do something, and that makes no sense right now". That could be "I'm in readonly mode and you invoked a mutation member", or "this method can't be called until some property is set" or "this method can't be called because you passed null in the ctor", or whatever.
HAL's "I'm afraid I can't do that, Dave." is InvalidOperationException thrown from hal.OpenDoors(DoorTypes.PodBay)... "I" can't do that, because of something that happened outside of this request. hal.OpenDoors(DoorTypes.PodBay | DoorTypes.EmergencyAirlockExterior) might throw an ArgumentException that only a single value can be requested, and that would, in HAL-ese, be "You know I can only open one kind of door at a time, Dave." (the error is Dave's, so ArgumentException)).
If @danmoseley 's Dan-mocracy is a De-mocracy, then I'll vote for fixing the exception type in the product code.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
InvalidOperationException means "you asked an object to do something, and that makes no sense right now".
The user is asking to convert this PaxGEA entry to another type, and that doesn't make sense right now, or ever.
Your exception text blames the cause of the exception on a parameter/argument, and
So maybe the text should be changed?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
doesn't make sense ... ever.
Right, so InvalidOperationException is the wrong exception. The exception isn't conditional on the target object's state (no fields/properties were consulted before the throw)
https://docs.microsoft.com/en-us/dotnet/api/system.invalidoperationexception?view=net-6.0
The exception that is thrown when a method call is invalid for the object's current state.
and from the remarks:
InvalidOperationException is used in cases when the failure to invoke a method is caused by reasons other than invalid arguments.
Since the reason here is entirely invalid arguments (the combination of "this method" (constructor) and "this argument" will NEVER work), it should be an ArgumentException.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Ok, I submitted it as a separate change to keep it as minimal as possible for a potential backport: #74845
The documentation changes in this PR should not matter for RC2, since intellisense will come from whatever we put in dotnet-api-docs.
| /// <param name="other">The <see cref="TarEntry"/> instance to convert to the GNU format.</param> | ||
| /// <exception cref="InvalidOperationException"><para><paramref name="other"/> is a <see cref="PaxGlobalExtendedAttributesTarEntry"/> instance.</para> | ||
| /// <para>-or-</para> | ||
| /// <para>The entry type of <paramref name="other"/> is not supported in the GNU format.</para></exception> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The same for this exception.
|
On a second thought, I'll include the docs changes in the other PR, since I'm adjusting all the exceptions. I'll close this in favor of #74845. |
No description provided.