Porting System.IO.Packaging source comments to Docs (#2303)

* Porting System.IO.Packaging source comments to Docs

* Apply suggestions from code review

Applying rpetrusha suggestions.

Co-Authored-By: carlossanlop <[email protected]>

Author: carlossanlop

xml/System.IO.Packaging/PackUriHelper.xml

@@ -475,6 +475,8 @@
         <altmember cref="M:System.IO.Packaging.PackUriHelper.ResolvePartUri(System.Uri,System.Uri)" />
         <related type="ExternalDocumentation" href="https://go.microsoft.com/fwlink/?LinkID=160055">Writing a Package Sample</related>
         <related type="ExternalDocumentation" href="https://go.microsoft.com/fwlink/?LinkID=71255">Open Packaging Conventions Specification</related>
+        <exception cref="T:System.ArgumentNullException"><paramref name="partUri" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="partUri" /> is not an absolute <see cref="T:System.Uri" />.</exception>
       </Docs>
     </Member>
     <Member MemberName="GetNormalizedPartUri">
@@ -523,6 +525,7 @@
         <altmember cref="M:System.IO.Packaging.PackUriHelper.GetPartUri(System.Uri)" />
         <altmember cref="M:System.IO.Packaging.PackUriHelper.GetPackageUri(System.Uri)" />
         <related type="ExternalDocumentation" href="https://go.microsoft.com/fwlink/?LinkID=71255">Open Packaging Conventions Specification</related>
+        <exception cref="T:System.ArgumentException"><paramref name="partUri" /> does not have a valid <see cref="T:System.Uri" /> syntax.</exception>
       </Docs>
     </Member>
     <Member MemberName="GetPackageUri">
@@ -570,6 +573,8 @@
         <altmember cref="Overload:System.IO.Packaging.PackUriHelper.Create" />
         <altmember cref="M:System.IO.Packaging.PackUriHelper.GetPartUri(System.Uri)" />
         <related type="ExternalDocumentation" href="https://go.microsoft.com/fwlink/?LinkID=71255">Open Packaging Conventions Specification</related>
+        <exception cref="T:System.ArgumentNullException"><paramref name="packUri" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="packUri" /> is not an absolute <see cref="T:System.Uri" />.</exception>
       </Docs>
     </Member>
     <Member MemberName="GetPartUri">
@@ -733,6 +738,7 @@
           <paramref name="sourcePartUri" /> or <paramref name="targetPartUri" /> is <see langword="null" />.</exception>
         <altmember cref="M:System.IO.Packaging.PackUriHelper.ResolvePartUri(System.Uri,System.Uri)" />
         <related type="ExternalDocumentation" href="https://go.microsoft.com/fwlink/?LinkID=71255">Open Packaging Conventions Specification</related>
+        <exception cref="T:System.ArgumentException">Either the <paramref name="sourcePartUri" /> or <paramref name="targetPartUri" /> does not have a valid <see cref="T:System.Uri" /> syntax.</exception>
       </Docs>
     </Member>
     <Member MemberName="GetSourcePartUriFromRelationshipPartUri">
@@ -939,4 +945,4 @@
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.IO.Packaging/PackageRelationshipSelector.xml

@@ -119,6 +119,7 @@ The <paramref name="sourceUri" /> is not the <see cref="T:System.IO.Packaging.Pa
         <returns>A list of relationships that match the selection parameters specified to the <see cref="M:System.IO.Packaging.PackageRelationshipSelector.#ctor(System.Uri,System.IO.Packaging.PackageRelationshipSelectorType,System.String)" /> constructor.</returns>
         <remarks>To be added.</remarks>
         <related type="ExternalDocumentation" href="https://go.microsoft.com/fwlink/?LinkId=74494">Digital Signing Framework of the Open Packaging Conventions</related>
+        <exception cref="T:System.ArgumentNullException"><paramref name="package" /> is <see langword="null" />.</exception>
       </Docs>
     </Member>
     <Member MemberName="SelectionCriteria">
@@ -234,4 +235,4 @@ The <paramref name="sourceUri" /> is not the <see cref="T:System.IO.Packaging.Pa
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.IO.Packaging/ZipPackage.xml

@@ -78,12 +78,15 @@
         <Parameter Name="compressionOption" Type="System.IO.Packaging.CompressionOption" />
       </Parameters>
       <Docs>
-        <param name="partUri">To be added.</param>
-        <param name="contentType">To be added.</param>
-        <param name="compressionOption">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="partUri">The Uri that represents the <see cref="T:System.IO.Packaging.PackagePart" />.</param>
+        <param name="contentType">A string representing the content type of the <see cref="T:System.IO.Packaging.PackagePart" />.</param>
+        <param name="compressionOption">The compression option to be used for this <see cref="T:System.IO.Packaging.PackagePart" />.</param>
+        <summary>Custom implementation for the underlying file format. Adds a new item to the zip archive corresponding to the <see cref="T:System.IO.Packaging.PackagePart" /> in the <see cref="T:System.IO.Packaging.ZipPackage" />.</summary>
         <returns>To be added.</returns>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException"><paramref name="partUri" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="partUri" /> does not have a valid <see cref="T:System.Uri" /> syntax.</exception>
+        <exception cref="T:System.ArgumentOutOfRangeException"><paramref name="compressionOption" /> does not have a valid <see cref="T:System.IO.Packaging.CompressionOption" /> value.</exception>
       </Docs>
     </Member>
     <Member MemberName="DeletePartCore">
@@ -113,9 +116,11 @@
         <Parameter Name="partUri" Type="System.Uri" />
       </Parameters>
       <Docs>
-        <param name="partUri">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="partUri">The Uri that represents the <see cref="T:System.IO.Packaging.PackagePart" />.</param>
+        <summary>This method is for a custom implementation specific to the file format. Deletes the <see cref="T:System.IO.Packaging.PackagePart" /> corresponding to the <see cref="T:System.Uri" /> specified. Attempting to delete a part that does not exist is not an error and so does not throw an exception.</summary>
         <remarks>To be added.</remarks>
+        <exception cref="T:System.ArgumentNullException"><paramref name="partUri" /> is <see langword="null" />.</exception>
+        <exception cref="T:System.ArgumentException"><paramref name="partUri" /> does not have a valid <see cref="T:System.Uri" /> syntax.</exception>
       </Docs>
     </Member>
     <Member MemberName="Dispose">
@@ -145,8 +150,8 @@
         <Parameter Name="disposing" Type="System.Boolean" />
       </Parameters>
       <Docs>
-        <param name="disposing">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="disposing"><see langword="true" /> if called during <see cref="M:System.IO.Packaging.ZipPackage.Dispose" />, <see langword="false" /> if called during <see cref="M:System.IO.Packaging.ZipPackage.Finalize" />.</param>
+        <summary>Closes the underlying <see cref="T:System.IO.Packaging.ZipPackage" /> object for this container.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -175,7 +180,7 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
+        <summary>This method is for a custom implementation corresponding to the underlying zip file format.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -206,8 +211,8 @@
         <Parameter Name="partUri" Type="System.Uri" />
       </Parameters>
       <Docs>
-        <param name="partUri">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="partUri">The Uri that represents the <see cref="T:System.IO.Packaging.PackagePart" />.</param>
+        <summary>This method is for a custom implementation specific to the file format. Returns a <see cref="T:System.IO.Packaging.PackagePart" /> after reading the actual physical bits. The method returns <see langword="null" /> to indicate that the part corresponding to the specified <see cref="T:System.Uri" />  was not found in the container. This method does not throw an exception if a part does not exist.</summary>
         <returns>To be added.</returns>
         <remarks>To be added.</remarks>
       </Docs>
@@ -237,10 +242,10 @@
       </ReturnValue>
       <Parameters />
       <Docs>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <summary>This method is for a custom implementation specific to the file format. This method retrieves the actual parts from the underlying <see cref="T:System.IO.Packaging.ZipPackage" />.</summary>
+        <returns>An array of <see cref="T:System.IO.Packaging.ZipPackagePart" /> objects.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>

xml/System.IO.Packaging/ZipPackagePart.xml

@@ -71,14 +71,13 @@
         <Parameter Name="access" Type="System.IO.FileAccess" Index="1" FrameworkAlternate="netframework-3.0;netframework-3.5;netframework-4.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8" />
       </Parameters>
       <Docs>
-        <param name="streamFileMode">To be added.</param>
-        <param name="mode">To be added.</param>
-        <param name="streamFileAccess">To be added.</param>
-        <param name="access">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <param name="mode">The I/O mode in which to open the stream.</param>
+        <param name="access">The access permissions with which the stream should be opened.</param>
+
+        <summary>Custom implementation for the GetStream method.</summary>
+        <returns>A stream corresponding to this <see cref="T:System.IO.Packaging.ZipPackagePart" />.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
   </Members>
-</Type>
+</Type>