Skip to content

docs: Add XML documentation to IZip interface #1737

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.

Sign up for GitHub

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

Merged
thomhurst merged 1 commit into from
Jan 1, 2026
Merged

docs: Add XML documentation to IZip interface #1737

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions src/ModularPipelines/Context/IZip.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,42 @@

namespace ModularPipelines.Context;

/// <summary>
/// Provides ZIP compression and decompression functionality for folders and files.
/// </summary>
public interface IZip
{
/// <summary>
/// Compresses a folder into a ZIP file using optimal compression level.
/// </summary>
/// <param name="folder">The folder to compress.</param>
/// <param name="outputPath">The path where the ZIP file will be created.</param>
/// <returns>A <see cref="File"/> representing the created ZIP file.</returns>
public File ZipFolder(Folder folder, string outputPath) => ZipFolder(folder, outputPath, CompressionLevel.Optimal);

/// <summary>
/// Compresses a folder into a ZIP file with the specified compression level.
/// </summary>
/// <param name="folder">The folder to compress.</param>
/// <param name="outputPath">The path where the ZIP file will be created.</param>
/// <param name="compressionLevel">The level of compression to use.</param>
/// <returns>A <see cref="File"/> representing the created ZIP file.</returns>
public File ZipFolder(Folder folder, string outputPath, CompressionLevel compressionLevel);

/// <summary>
/// Extracts a ZIP file to a folder, overwriting existing files by default.
/// </summary>
/// <param name="zipPath">The path to the ZIP file to extract.</param>
/// <param name="outputFolderPath">The path where the contents will be extracted.</param>
/// <returns>A <see cref="Folder"/> representing the extraction destination folder.</returns>
public Folder UnZipToFolder(string zipPath, string outputFolderPath) => UnZipToFolder(zipPath, outputFolderPath, true);

/// <summary>
/// Extracts a ZIP file to a folder with control over whether to overwrite existing files.
/// </summary>
/// <param name="zipPath">The path to the ZIP file to extract.</param>
/// <param name="outputFolderPath">The path where the contents will be extracted.</param>
/// <param name="overwriteFiles">If <c>true</c>, existing files will be overwritten; otherwise, an exception is thrown for conflicts.</param>
/// <returns>A <see cref="Folder"/> representing the extraction destination folder.</returns>
Comment on lines +42 to +43

Copilot AI Jan 1, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation states "an exception is thrown for conflicts" but this could be more specific. The underlying ZipFile.ExtractToDirectory method throws an IOException when overwriteFiles is false and a file already exists. Consider being more specific about the exception type for better clarity, similar to how other interfaces in the codebase use specific exception documentation (see IModuleContext which uses <exception> tags).

Suggested change
/// <param name="overwriteFiles">If <c>true</c>, existing files will be overwritten; otherwise, an exception is thrown for conflicts.</param>
/// <returns>A <see cref="Folder"/> representing the extraction destination folder.</returns>
/// <param name="overwriteFiles">If <c>true</c>, existing files will be overwritten; otherwise, an <see cref="System.IO.IOException"/> is thrown when a file conflict occurs.</param>
/// <returns>A <see cref="Folder"/> representing the extraction destination folder.</returns>
/// <exception cref="System.IO.IOException">Thrown when <paramref name="overwriteFiles"/> is <c>false</c> and a file to be extracted already exists in the destination.</exception>

Copilot uses AI. Check for mistakes.
public Folder UnZipToFolder(string zipPath, string outputFolderPath, bool overwriteFiles);
}
Loading