adds some xml doc to image api

PiwigoDotnet/Piwigo.Client/IImageApi.cs

@@ -4,13 +4,89 @@ namespace Piwigo.Client;
 
 public interface IImageApi
 {
+    /// <summary>
+    ///     Adds an image to piwigo after all parts have been uploaded.
+    /// </summary>
+    /// <param name="imageUpload">The metadata of the uploaded image</param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns>Information about the uploaded image</returns>
+    /// <remarks>Ensure that you called <see cref="AddChunkAsync" /> for every chunk of the image.</remarks>
     Task<ImageUploaded> AddAsync(ImageUpload imageUpload, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    ///     Updates an image to piwigo after all parts have been uploaded.
+    /// </summary>
+    /// <param name="imageId">The image id to update</param>
+    /// <param name="imageUpload">The metadata of the uploaded image</param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns>Information about the uploaded image</returns>
+    /// <remarks>Ensure that you called <see cref="AddChunkAsync" /> for every chunk of the image.</remarks>
     Task<ImageUploaded> UpdateAsync(int imageId, ImageUpload imageUpload, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    ///     Adds a comment to the given image.
+    /// </summary>
+    /// <param name="imageId">The id of the image</param>
+    /// <param name="author">The author</param>
+    /// <param name="content">The content</param>
+    /// <param name="key">
+    ///     The key to post: The key can read from <see cref="GetInfoAsync" /> and <see cref="CommentPost.Key" />
+    /// </param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns>The id of the new comment</returns>
     Task<int> AddCommentAsync(int imageId, string? author, string content, string key, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    ///     Adds a chunk of an image to piwigo.
+    ///     This enables uploading of large images using multiple chunks of data.
+    /// </summary>
+    /// <param name="data">The chunk to upload</param>
+    /// <param name="originalSum">The original image checksum</param>
+    /// <param name="position">The chunk position</param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
     Task AddChunkAsync(byte[] data, string originalSum, int position, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    ///     Checks if piwigo is ready to get images uploaded.
+    /// </summary>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns>true if ready; otherwise false</returns>
     Task<bool> ReadyForUploadAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    ///     Gets detailed information about the image.
+    /// </summary>
+    /// <param name="imageId">The image id to read</param>
+    /// <param name="commentsPage">The requested comments page</param>
+    /// <param name="commentsPerPage">Number of comments per page</param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns>The metadata of a given image id</returns>
     Task<Image> GetInfoAsync(int imageId, int? commentsPage, int? commentsPerPage, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    ///     Gets a list of images for a given album.
+    /// </summary>
+    /// <param name="albumId">The album id</param>
+    /// <param name="recursive">true to get images from sub-albums</param>
+    /// <param name="page">Information about the paging</param>
+    /// <param name="filter">Filter criteria applied to the returned images</param>
+    /// <param name="order">How the list should be sorted</param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns>a paged list of the images of a given album</returns>
     Task<PagedImages> GetImages(int albumId, bool recursive, PagingInfo page, ImageFilter filter, ImageOrder order = ImageOrder.Name,
         CancellationToken cancellationToken = default);