From 49ec268c3de7064fde6d98b91b1019ec8fd27dfb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Philipp=20H=C3=A4felfinger?= <philipp@haefelfinger.ch>
Date: Thu, 27 Oct 2022 23:05:51 +0200
Subject: [PATCH] adds comments for the album api

---
 src/Piwigo.Client/Albums/IAlbumApi.cs | 100 ++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)

diff --git a/src/Piwigo.Client/Albums/IAlbumApi.cs b/src/Piwigo.Client/Albums/IAlbumApi.cs
index 5c5c85f..a9fa74f 100644
--- a/src/Piwigo.Client/Albums/IAlbumApi.cs
+++ b/src/Piwigo.Client/Albums/IAlbumApi.cs
@@ -2,24 +2,124 @@ namespace Piwigo.Client.Albums;
 
 public interface IAlbumApi
 {
+    /// <summary>
+    ///     Calculates the number of orphans for a given album
+    /// </summary>
+    /// <param name="albumId">the album id</param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns>Information about images that would become orphan</returns>
     Task<AlbumOrphans> CalculateOrphansAsync(int albumId, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    ///     Deletes an album
+    /// </summary>
+    /// <param name="albumId">album id to delete</param>
+    /// <param name="apiToken">The API token that can be read from <see cref="Piwigo.Client.Session.SessionStatus" /></param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns></returns>
     Task DeleteAsync(int albumId, string apiToken, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    ///     Moves an album into another album as a sub-album
+    /// </summary>
+    /// <param name="albumId">album id to move</param>
+    /// <param name="parentAlbumId">new parent album id</param>
+    /// <param name="apiToken">The API token that can be read from <see cref="Piwigo.Client.Session.SessionStatus" /></param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns></returns>
     Task MoveAsync(int albumId, int parentAlbumId, string apiToken, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    ///     deletes the album image used in the album overview
+    /// </summary>
+    /// <param name="albumId">album id that should get cleared</param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns></returns>
     Task DeleteRepresentativeAsync(int albumId, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    ///     performs a refresh of the album title image.
+    /// </summary>
+    /// <param name="albumId">album id to refresh</param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns></returns>
     Task RefreshRepresentativeAsync(int albumId, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    ///     Sets the representative image for the given album id
+    /// </summary>
+    /// <param name="albumId">album id that gets a new representative image</param>
+    /// <param name="imageId">image id to use for the given album</param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns></returns>
     Task SetRepresentativeAsync(int albumId, int imageId, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    ///     Sets the rank of a given album
+    /// </summary>
+    /// <param name="albumId">album id</param>
+    /// <param name="rank"></param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns></returns>
     Task SetRankAsync(int albumId, int rank, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    ///     sets album information
+    /// </summary>
+    /// <param name="albumId">the album id to update</param>
+    /// <param name="name">the album name</param>
+    /// <param name="comment">a comment to describe the album</param>
+    /// <param name="status">the status <see cref="AlbumStatus" /></param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns></returns>
     Task SetInfoAsync(int albumId, string name, string? comment, AlbumStatus? status, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    ///     adds an album to the gallery
+    /// </summary>
+    /// <param name="name">name of the album</param>
+    /// <param name="parentId">an optional parent album id if you create a new sub album</param>
+    /// <param name="comment">a comment to describe the album</param>
+    /// <param name="visible">true if the album is visible; false to hide it</param>
+    /// <param name="status">the status <see cref="AlbumStatus" /></param>
+    /// <param name="commentable">true to enable comments on the images; false otherwise</param>
+    /// <param name="position">the position of the album</param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns></returns>
     Task<int> AddAsync(string name, int? parentId = null, string? comment = null, bool? visible = null, AlbumStatus? status = null, bool? commentable = null,
         AlbumPosition? position = null, CancellationToken cancellationToken = default);
 
+    /// <summary>
+    ///     Gets a list of albums
+    /// </summary>
+    /// <param name="albumId">provides an album as a starting point to get sub-albums</param>
+    /// <param name="recursive">tells if the sub albums should get recursively</param>
+    /// <param name="fullName">
+    ///     ture to get the full name of an album e.g. 'UnitTestMain / UnitTestSub1' while false only
+    ///     returns 'UnitTestSub1'
+    /// </param>
+    /// <param name="thumbnailSize">defines the size of the album thumbnail</param>
+    /// <param name="cancellationToken">
+    ///     <see cref="CancellationToken" />
+    /// </param>
+    /// <returns></returns>
     Task<IReadOnlyCollection<Album>> GetListAsync(int? albumId, bool? recursive, bool? fullName, ThumbnailSize? thumbnailSize, CancellationToken cancellationToken = default);
 }
\ No newline at end of file