Skip to content

Commit 5353305

Browse files
carlossanlopRon Petrusha
carlossanlop
authored and
Ron Petrusha
committed
Porting source comments from System.IO.Compression (#2296)
* Ported triple slash source comments for System.IO.Compression * Restored overwrite to overwriteFiles, it was correct. * Apply suggestions from code review Applying rpetrusha suggestions. Co-Authored-By: carlossanlop <[email protected]>
1 parent c4204c6 commit 5353305

File tree

2 files changed

+154
-18
lines changed

2 files changed

+154
-18
lines changed

‎xml/System.IO.Compression/ZipFile.xml

Lines changed: 115 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -473,11 +473,62 @@
473473
<Parameter Name="overwriteFiles" Type="System.Boolean" Index="2" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
474474
</Parameters>
475475
<Docs>
476-
<param name="sourceArchiveFileName">To be added.</param>
477-
<param name="destinationDirectoryName">To be added.</param>
478-
<param name="overwriteFiles">To be added.</param>
479-
<summary>To be added.</summary>
480-
<remarks>To be added.</remarks>
476+
<param name="sourceArchiveFileName">The path on the file system to the archive that is to be extracted.</param>
477+
<param name="destinationDirectoryName">The path to the destination directory on the file system. The directory specified must not exist, but the directory that it is contained in must exist.</param>
478+
<param name="overwriteFiles"><see langword="true" /> to overwrite files; <see langword="false" /> otherwise.</param>
479+
<summary>Extracts all of the files in the specified archive to a directory on the file system.</summary>
480+
<remarks>
481+
<format type="text/markdown">
482+
<![CDATA[
483+
## Remarks
484+
The specified directory must not exist. The method creates the specified directory and all subdirectories.
485+
486+
If there is an error while extracting the archive, the archive will remain partially extracted.
487+
488+
Each entry will be extracted such that the extracted file has the same relative path to the `destinationDirectoryName` as the entry has to the archive.
489+
490+
The path can specify relative or absolute path information. A relative path is interpreted as relative to the current working directory.
491+
492+
If a file to be archived has an invalid last modified time, the first date and time representable in the Zip timestamp format (midnight on January 1, 1980) will be used.
493+
494+
]]></format>
495+
</remarks>
496+
<exception cref="T:System.ArgumentException"><paramref name="sourceArchiveFileName" /> or <paramref name="destinationDirectoryName" /> is a zero-length string, contains only whitespace, or contains one or more invalid characters as defined by <see cref="F:System.IO.Path.InvalidPathChars" />.</exception>
497+
<exception cref="T:System.ArgumentNullException"><paramref name="sourceArchiveFileName" /> or <paramref name="destinationDirectoryName" /> is <see langword="null" />.</exception>
498+
<exception cref="T:System.IO.PathTooLongException"><paramref name="sourceArchiveFileName" /> or <paramref name="destinationDirectoryName" /> specifies a path, a file name, or both that exceed the system-defined maximum length. </exception>
499+
<exception cref="T:System.IO.DirectoryNotFoundException">The path specified by <paramref name="sourceArchiveFileName" /> or <paramref name="destinationDirectoryName" /> is invalid (for example, it is on an unmapped drive).</exception>
500+
<exception cref="T:System.IO.IOException">The directory specified by <paramref name="destinationDirectoryName" /> already exists.
501+
502+
-or-
503+
504+
An I/O error has occurred.
505+
506+
-or-
507+
508+
The name of a <see cref="T:System.IO.Compression.ZipArchiveEntry" /> is zero-length, contains only whitespace, or contains one or more invalid characters as defined by <see cref="F:System.IO.Path.InvalidPathChars" />.
509+
510+
-or-
511+
512+
Extracting a <see cref="T:System.IO.Compression.ZipArchiveEntry" /> would result in a file destination that is outside the destination directory (for example, because of parent directory accessors).
513+
514+
-or-
515+
516+
A <see cref="T:System.IO.Compression.ZipArchiveEntry" /> has the same name as an already extracted entry from the same archive.</exception>
517+
<exception cref="T:System.UnauthorizedAccessException">The caller does not have the required permission.</exception>
518+
<exception cref="T:System.NotSupportedException">
519+
<paramref name="sourceArchiveFileName" /> or <paramref name="destinationDirectoryName" /> is in an invalid format. </exception>
520+
<exception cref="T:System.IO.FileNotFoundException">
521+
<paramref name="sourceArchiveFileName" /> was not found.
522+
</exception>
523+
<exception cref="T:System.IO.InvalidDataException">The archive specified by <paramref name="sourceArchiveFileName" /> is not a valid <see cref="T:System.IO.Compression.ZipArchive" />.
524+
525+
-or-
526+
527+
A <see cref="T:System.IO.Compression.ZipArchiveEntry" /> was not found or was corrupt.
528+
529+
-or-
530+
531+
A <see cref="T:System.IO.Compression.ZipArchiveEntry" /> has been compressed using a compression method that is not supported.</exception>
481532
</Docs>
482533
</Member>
483534
<Member MemberName="ExtractToDirectory">
@@ -607,12 +658,64 @@
607658
<Parameter Name="overwriteFiles" Type="System.Boolean" Index="3" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
608659
</Parameters>
609660
<Docs>
610-
<param name="sourceArchiveFileName">To be added.</param>
611-
<param name="destinationDirectoryName">To be added.</param>
612-
<param name="entryNameEncoding">To be added.</param>
613-
<param name="overwriteFiles">To be added.</param>
614-
<summary>To be added.</summary>
615-
<remarks>To be added.</remarks>
661+
<param name="sourceArchiveFileName">The path on the file system to the archive that is to be extracted.</param>
662+
<param name="destinationDirectoryName">The path to the destination directory on the file system. The directory specified must not exist, but the directory that it is contained in must exist.</param>
663+
<param name="entryNameEncoding">The encoding to use when reading entry names in this <see cref="T:System.IO.Compression.ZipArchive" />.</param>
664+
<param name="overwriteFiles"><see langword="true" /> to overwrite files; <see langword="false" /> otherwise.</param>
665+
<summary>Extracts all of the files in the specified archive to a directory on the file system.</summary>
666+
<remarks>
667+
<format type="text/markdown"><![CDATA[
668+
## Remarks
669+
The specified directory must not exist. This method will create the specified directory and all subdirectories.
670+
671+
If there is an error while extracting the archive, the archive will remain partially extracted.
672+
673+
Each entry will be extracted such that the extracted file has the same relative path to the `destinationDirectoryName` as the entry has to the archive.
674+
675+
The path can specify relative or absolute path information. A relative path is interpreted as relative to the current working directory.
676+
677+
If a file to be archived has an invalid last modified time, the first date and time representable in the Zip timestamp format (midnight on January 1, 1980) will be used.
678+
679+
]]>
680+
</format>
681+
</remarks>
682+
<exception cref="T:System.ArgumentException"><paramref name="sourceArchiveFileName" /> or <paramref name="destinationDirectoryName" /> is a zero-length string, contains only whitespace, or contains one or more invalid characters as defined by <see cref="F:System.IO.Path.InvalidPathChars" />.
683+
684+
-or-
685+
686+
<paramref name="entryNameEncoding" /> is set to a Unicode encoding other than UTF-8.</exception>
687+
<exception cref="T:System.ArgumentNullException"><paramref name="sourceArchiveFileName" /> or <paramref name="destinationDirectoryName" /> is <see langword="null" />.</exception>
688+
<exception cref="T:System.IO.PathTooLongException"><paramref name="sourceArchiveFileName" /> or <paramref name="destinationDirectoryName" /> specifies a path, a file name, or both that exceed the system-defined maximum length. </exception>
689+
<exception cref="T:System.IO.DirectoryNotFoundException">The path specified by <paramref name="sourceArchiveFileName" /> or <paramref name="destinationDirectoryName" /> is invalid (for example, it is on an unmapped drive).</exception>
690+
<exception cref="T:System.IO.IOException">The directory specified by <paramref name="destinationDirectoryName" /> already exists.
691+
692+
-or-
693+
694+
An I/O error has occurred.
695+
696+
-or-
697+
698+
The name of a <see cref="T:System.IO.Compression.ZipArchiveEntry" /> is zero-length, contains only whitespace, or contains one or more invalid characters as defined by <see cref="F:System.IO.Path.InvalidPathChars" />.
699+
700+
-or-
701+
702+
Extracting a <see cref="T:System.IO.Compression.ZipArchiveEntry" /> would result in a file destination that is outside the destination directory (for example, because of parent directory accessors).
703+
704+
-or-
705+
706+
A <see cref="T:System.IO.Compression.ZipArchiveEntry" /> has the same name as an already extracted entry from the same archive.</exception>
707+
<exception cref="T:System.UnauthorizedAccessException">The caller does not have the required permission.</exception>
708+
<exception cref="T:System.NotSupportedException"><paramref name="sourceArchiveFileName" /> or <paramref name="destinationDirectoryName" /> is in an invalid format. </exception>
709+
<exception cref="T:System.IO.FileNotFoundException"><paramref name="sourceArchiveFileName" /> was not found.</exception>
710+
<exception cref="T:System.IO.InvalidDataException">The archive specified by <paramref name="sourceArchiveFileName" /> is not a valid <see cref="T:System.IO.Compression.ZipArchive" />.
711+
712+
-or-
713+
714+
An archive entry was not found or was corrupt.
715+
716+
-or-
717+
718+
An archive entry has been compressed using a compression method that is not supported.</exception>
616719
</Docs>
617720
</Member>
618721
<MemberGroup MemberName="Open">
@@ -905,4 +1008,4 @@
9051008
</Docs>
9061009
</Member>
9071010
</Members>
908-
</Type>
1011+
</Type>

‎xml/System.IO.Compression/ZipFileExtensions.xml

Lines changed: 39 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -361,11 +361,44 @@
361361
<Parameter Name="overwriteFiles" Type="System.Boolean" Index="2" FrameworkAlternate="netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netstandard-2.1" />
362362
</Parameters>
363363
<Docs>
364-
<param name="source">To be added.</param>
365-
<param name="destinationDirectoryName">To be added.</param>
366-
<param name="overwriteFiles">To be added.</param>
367-
<summary>To be added.</summary>
368-
<remarks>To be added.</remarks>
364+
<param name="source">The <see cref="T:System.IO.Compression.ZipArchive" /> to extract.</param>
365+
<param name="destinationDirectoryName">The path to the destination directory on the file system. The path can be relative or absolute. A relative path is interpreted as relative to the current working directory.</param>
366+
<param name="overwriteFiles"><see langword="true" /> to indicate that existing files are to be overwritten; <see langword="false" /> otherwise.</param>
367+
<summary>Extracts all of the files in the archive to a directory on the file system. </summary>
368+
<remarks>
369+
<format type="text/markdown"><![CDATA[
370+
## Remarks
371+
The specified directory may already exist. This method will create the specified directory and all subdirectories if necessary.
372+
373+
If there is an error while extracting the archive, the archive will remain partially extracted.
374+
375+
Each entry will be extracted such that the extracted file has the same relative path to `destinationDirectoryName` as the entry has to the root of the archive.
376+
377+
If a file to be archived has an invalid last modified time, the first date and time representable in the Zip timestamp format (midnight on January 1, 1980) will be used.
378+
379+
]]></format>
380+
</remarks>
381+
<exception cref="T:System.ArgumentException"><paramref name="destinationArchiveFileName" /> is a zero-length string, contains only whitespace,
382+
or contains one or more invalid characters as defined by <see cref="F:System.IO.Path.InvalidPathChars" />.</exception>
383+
<exception cref="T:System.ArgumentNullException"><paramref name="destinationArchiveFileName" /> is <see langword="null" />.</exception>
384+
<exception cref="T:System.IO.PathTooLongException">The specified path, file name, or both exceed the system-defined maximum length. </exception>
385+
<exception cref="T:System.IO.DirectoryNotFoundException">The specified path is invalid, (for example, it is on an unmapped drive).</exception>
386+
<exception cref="T:System.IO.IOException">The name of a <see cref="T:System.IO.Compression.ZipArchiveEntry" /> is zero-length, contains only whitespace, or contains one or more invalid characters as defined by <see cref="F:System.IO.Path.InvalidPathChars" />.
387+
388+
-or-
389+
390+
Extracting a <see cref="T:System.IO.Compression.ZipArchiveEntry" /> would have resulted in a destination file that is outside <paramref name="destinationArchiveFileName" /> (for example, if the entry name contains parent directory accessors).
391+
392+
-or-
393+
394+
A <see cref="T:System.IO.Compression.ZipArchiveEntry" /> has the same name as an already extracted entry from the same archive.</exception>
395+
<exception cref="T:System.UnauthorizedAccessException">The caller does not have the required permission.</exception>
396+
<exception cref="T:System.NotSupportedException"><paramref name="destinationArchiveFileName" /> is in an invalid format. </exception>
397+
<exception cref="T:System.IO.InvalidDataException">A <see cref="T:System.IO.Compression.ZipArchiveEntry" /> was not found or was corrupt.
398+
399+
-or-
400+
401+
A <see cref="T:System.IO.Compression.ZipArchiveEntry" /> has been compressed using a compression method that is not supported.</exception>
369402
</Docs>
370403
</Member>
371404
<MemberGroup MemberName="ExtractToFile">
@@ -570,4 +603,4 @@
570603
</Docs>
571604
</Member>
572605
</Members>
573-
</Type>
606+
</Type>

0 commit comments

Comments
 (0)