Merge pull request #360 from ITU-BDSA2024-GROUP10/documentation

Documentation

Chirp/src/Chirp.Core/AuthorService.cs

@@ -1,16 +1,69 @@
+using Chirp.Core.CustomException;
 using Chirp.Core.DTO;
 
 namespace Chirp.Core;
 
+/// <summary>
+/// The IAuthorService defines what information you can get from an Author 
+/// </summary>
 public interface IAuthorService
 {
+    /// <summary>
+    /// Gets the Users followed by the given User
+    /// </summary>
+    /// <param name="username"></param>
+    /// <exception cref="UserDoesNotExist">Thrown if a user with the given username doesn't exist</exception>
     public IEnumerable<AuthorDTO> GetFollows(string username);
+
+    /// <summary>
+    /// Gets the Users that follow the given User
+    /// </summary>
+    /// <param name="username"></param>
+    /// <exception cref="UserDoesNotExist">Thrown if a user with the given username doesn't exist</exception>
     public IEnumerable<AuthorDTO> GetFollowers(string username);
-    public bool Follow(string currentUser, string userToFollow);
-    public bool Unfollow(string currentUser, string userToUnFollow);
+
+    /// <summary>
+    /// Makes a User follow some other User
+    /// </summary>
+    /// <param name="userWhoFollow">username</param>
+    /// <param name="userToFollow">username</param>
+    /// <returns>True if the follow went through, false if there already exists a follow connection between the two users</returns>
+    /// <exception cref="UserDoesNotExist">Thrown if one of the users doesn't exist</exception>
+    /// <exception cref="ArgumentException">Thrown if the value of <paramref name="userWhoFollow"/> is equal to <paramref name="userToFollow"/>.
+    /// </exception>
+    public bool Follow(string userWhoFollow, string userToFollow);
+
+    /// <summary>
+    /// Makes a User unfollow some other User
+    /// </summary>
+    /// <param name="userWhoFollows">username</param>
+    /// <param name="userToUnFollow">username</param>
+    /// <returns>True if the unfollow went through, false if there isn't a follow connection between the two users</returns>
+    /// <exception cref="UserDoesNotExist">Thrown if one of the users doesn't exist</exception>
+    /// <exception cref="ArgumentException">Thrown if the value of <paramref name="userWhoFollows"/> is equal to <paramref name="userToUnFollow"/>.
+    /// </exception>
+    public bool Unfollow(string userWhoFollows, string userToUnFollow);
+
+    /// <summary>
+    /// Makes all Users which follow the given User, unfollow them
+    /// </summary>
+    /// <param name="username"></param>
+    /// <returns>True if the followers unfollowed</returns>
+    /// <exception cref="UserDoesNotExist">Thrown if a user with the given username doesn't exist</exception>
     public bool MakeFollowersUnfollow(string username);
+
+    /// <summary>
+    /// Gets all Comments made by the given User
+    /// </summary>
+    /// <param name="username"></param>
+    /// <exception cref="UserDoesNotExist">Thrown if a user with the given username doesn't exist</exception>
     public IEnumerable<CommentDTO> GetComments(string username);
-    public IEnumerable<AuthorDTO?> GetAuthorsByNames(IEnumerable<String> names);
+
+    /// <summary>
+    /// Gets all authors with one of the given usernames
+    /// </summary>
+    /// <param name="usernames"></param>
+    public IEnumerable<AuthorDTO?> GetAuthorsByNames(IEnumerable<String> usernames);
 }
 
 public class AuthorService(IAuthorRepository db) : IAuthorService
@@ -35,18 +88,18 @@ public IEnumerable<CommentDTO> GetComments(string username)
         return db.GetComments(username).Result;
     }
 
-    public bool Follow(string currentUser, string userToFollow)
+    public bool Follow(string userWhoFollow, string userToFollow)
     {
-        return db.Follow(currentUser, userToFollow).Result;
+        return db.Follow(userWhoFollow, userToFollow).Result;
     }
 
-    public bool Unfollow(string currentUser, string userToUnFollow)
+    public bool Unfollow(string userWhoFollows, string userToUnFollow)
     {
-        return db.UnFollow(currentUser, userToUnFollow).Result;
+        return db.UnFollow(userWhoFollows, userToUnFollow).Result;
     }
-    
-    public IEnumerable<AuthorDTO?> GetAuthorsByNames(IEnumerable<String> names)
+
+    public IEnumerable<AuthorDTO?> GetAuthorsByNames(IEnumerable<String> usernames)
     {
-        return db.GetAuthorsByNames(names).Result;
+        return db.GetAuthorsByNames(usernames).Result;
     }
 }

Chirp/src/Chirp.Core/CheepService.cs

@@ -2,70 +2,169 @@
 
 namespace Chirp.Core;
 
+/// <summary>
+/// The ICheepService Interface describes what information you can get from a Cheep
+/// </summary>
 public interface ICheepService
 {
+    /// <summary>
+    /// Gets all Cheeps on the given page by the given page size
+    /// </summary>
+    /// <param name="page">if it's less than or equal to zero, It's treated as 1</param>
+    /// <param name="pageSize">how many cheeps are on a page. Must be greater than zero</param>
+    /// <exception cref="ArgumentOutOfRangeException">Thrown if the <paramref name="pageSize"/> is less than one</exception>
     public IEnumerable<CheepDTO> GetCheepsByPage(int page, int pageSize);
-    public IEnumerable<CheepDTO> GetCheepsFromAuthorByPage(string author, int page, int pageSize);
-    public IEnumerable<CheepDTO> GetCheepsFromAuthorsByPage(IEnumerable<string> authors, int page, int pageSize);
-    public IEnumerable<CheepDTO> GetCheepsFromAuthor(string author);
+
+    /// <summary>
+    /// Gets Cheeps made by the authors with one of the given usernames by the given page and page size
+    /// </summary>
+    /// <param name="usernames"></param>
+    /// <param name="page">if it's less than or equal to zero, It's treated as 1</param>
+    /// <param name="pageSize">how many cheeps are on a page. Must be greater than zero</param>
+    /// <exception cref="ArgumentOutOfRangeException">Thrown if the <paramref name="pageSize"/> is less than one</exception>
+    public IEnumerable<CheepDTO> GetCheepsFromAuthorsByPage(IEnumerable<string> usernames, int page, int pageSize);
+
+    /// <summary>
+    /// Gets all Cheeps made by the author with the given username
+    /// </summary>
+    /// <param name="username"></param>
+    public IEnumerable<CheepDTO> GetCheepsFromAuthor(string username);
+
+    /// <summary>
+    /// Gets the amount of pages cheeped by an author with a given page size
+    /// </summary>
+    /// <param name="pageSize">how many cheeps are on a page. Must be greater than zero</param>
+    /// <returns>The result is rounded to the next larger int</returns>
+    /// <exception cref="ArgumentOutOfRangeException">Thrown if the <paramref name="pageSize"/> is less than one</exception>
     public int GetAmountOfCheepPages(int pageSize);
-    public int GetAmountOfCheepPagesFromAuthors(IEnumerable<String> authors, int pageSize);
+
+    /// <summary>
+    /// Gets the amount of pages cheeped by a collection of authors with a given page size
+    /// </summary>
+    /// <param name="usernames">the usernames of the authors</param>
+    /// <param name="pageSize">how many cheeps are on a page. Must be greater than zero</param>
+    /// <returns>the result is rounded to the next larger int</returns>
+    /// <exception cref="ArgumentOutOfRangeException">Thrown if the <paramref name="pageSize"/> is less than one</exception>
+    public int GetAmountOfCheepPagesFromAuthors(IEnumerable<string> usernames, int pageSize);
+
+    /// <summary>
+    /// Creates a new Cheep from the given CheepDTO
+    /// </summary>
+    /// <param name="cheep"></param>
+    /// <returns>True if a cheep was successfully created,
+    /// false if the author said to have created the cheep doesn't exist</returns>
     public bool CreateCheep(CheepDTO cheep);
-    public bool AddCommentToCheep(CommentDTO comment);
+
+    /// <summary>
+    /// Creates a new comment from the given CommentDTO
+    /// </summary>
+    /// <param name="comment"></param>
+    /// <returns>True if a comment was successfully created,
+    /// false if either the author said to have created the comment,
+    /// or the cheep said to have been commented, doesn't exist</returns>
+    public bool CreateComment(CommentDTO comment);
+
+    /// <summary>
+    /// Gets the amount of Comments associated with the cheep that has the given CheepId
+    /// </summary>
+    /// <param name="cheepId"></param>
+    /// <returns>If <paramref name="cheepId"/> is null, 0 is returned</returns>
     public int GetCommentAmountOnCheep(int? cheepId);
+
+    /// <summary>
+    /// Gets the Cheep associated with the given CheepId
+    /// </summary>
+    /// <param name="cheepId"></param>
     public CheepDTO GetCheepFromId(int cheepId);
+
+    /// <summary>
+    /// Gets all Comments associated with the cheep that has the given CheepId
+    /// </summary>
+    /// <param name="cheepId"></param>
     public IEnumerable<CommentDTO> GetCommentsFromCheep(int cheepId);
+
+    /// <summary>
+    /// Makes an author like some Cheep, described by the LikeDTO
+    /// </summary>
+    /// <param name="like"></param>
+    /// <returns>True if the like went through,
+    /// false if the author said to have liked the cheep,
+    /// or if the cheep said to have been liked doesn't exist</returns>
     public bool LikeCheep(LikeDTO like);
+
+    /// <summary>
+    /// Makes an author unlike some Cheep, described by the LikeDTO
+    /// </summary>
+    /// <param name="like"></param>
+    /// <returns>True if the unlike went through,
+    /// false if the cheep said to have been unliked doesn't exist,
+    /// or if the cheep isn't liked by the author it is said to be liked by</returns>
     public bool UnlikeCheep(LikeDTO like);
+
+    /// <summary>
+    /// Gets how many Likes are associated with some Cheep given the CheepId
+    /// </summary>
+    /// <param name="cheepId"></param>
+    /// <returns>0 if there isn't a cheep associated with the given <paramref name="cheepId"/></returns>
     public Task<int> GetLikeCount(int cheepId);
-    public Task<bool> HasUserLikedCheep(int cheepId, string author);
+
+    /// <summary>
+    /// Returns whether an author with the given username has liked the cheep with the given CheepId
+    /// </summary>
+    /// <param name="cheepId"></param>
+    /// <param name="username"></param>
+    public Task<bool> HasUserLikedCheep(int cheepId, string username);
 }
 
+/// <summary>
+/// The CheepService class handles calls to the CheepRepository from the UI 
+/// </summary>
+/// <param name="db"></param>
 public class CheepService(ICheepRepository db) : ICheepService
 {
     public IEnumerable<CheepDTO> GetCheepsByPage(int page, int pageSize)
     {
-        ArgumentOutOfRangeException.ThrowIfNegative(pageSize);
+        ArgumentOutOfRangeException.ThrowIfLessThan(pageSize, 1);
 
         var result = db.GetCheepsByPage(page, pageSize).Result ??
                      throw new ArgumentNullException(nameof(db.GetCheepsByPage));
 
         return result.ToList();
     }
 
-    public IEnumerable<CheepDTO> GetCheepsFromAuthor(string author)
+    public IEnumerable<CheepDTO> GetCheepsFromAuthor(string username)
     {
-        return db.GetCheepsFromAuthor(author).Result.ToList();
+        return db.GetCheepsFromAuthor(username).Result.ToList();
     }
 
-    public IEnumerable<CheepDTO> GetCheepsFromAuthorByPage(string author, int page, int pageSize)
+    public IEnumerable<CheepDTO> GetCheepsFromAuthorsByPage(IEnumerable<string> usernames, int page, int pageSize)
     {
-        return db.GetCheepsFromAuthorByPage(author, page, pageSize).Result.ToList();
-    }
-
-    public IEnumerable<CheepDTO> GetCheepsFromAuthorsByPage(IEnumerable<string> authors, int page, int pageSize)
-    {
-        return db.GetCheepsFromAuthorsByPage(authors, page, pageSize).Result.ToList();
+        ArgumentOutOfRangeException.ThrowIfLessThan(pageSize, 1);
+        return db.GetCheepsFromAuthorsByPage(usernames, page, pageSize).Result.ToList();
     }
 
     public int GetAmountOfCheepPages(int pageSize)
     {
+        ArgumentOutOfRangeException.ThrowIfLessThan(pageSize, 1);
+
         return (int)Math.Ceiling(db.GetAmountOfCheeps().Result / (double)pageSize);
     }
 
-    public int GetAmountOfCheepPagesFromAuthors(IEnumerable<String> authors, int pageSize)
+    public int GetAmountOfCheepPagesFromAuthors(IEnumerable<String> usernames, int pageSize)
     {
-        return (int)Math.Ceiling(db.GetAmountOfCheepsFromAuthors(authors).Result / (double)pageSize);
+        ArgumentOutOfRangeException.ThrowIfLessThan(pageSize, 1);
+
+        return (int)Math.Ceiling(db.GetAmountOfCheepsFromAuthors(usernames).Result / (double)pageSize);
     }
 
     public bool CreateCheep(CheepDTO cheep)
     {
         return db.CreateCheep(cheep).Result;
     }
 
-    public bool AddCommentToCheep(CommentDTO comment)
+    public bool CreateComment(CommentDTO comment)
     {
-        return db.AddCommentToCheep(comment).Result;
+        return db.CreateComment(comment).Result;
     }
 
     public int GetCommentAmountOnCheep(int? cheepId)
@@ -80,7 +179,7 @@ public CheepDTO GetCheepFromId(int cheepId)
 
     public IEnumerable<CommentDTO> GetCommentsFromCheep(int cheepId)
     {
-        return db.GetCommentsForCheep(cheepId).Result.ToList();
+        return db.GetCommentsForCheep(cheepId).Result;
     }
 
     public bool LikeCheep(LikeDTO like)
@@ -98,8 +197,8 @@ public async Task<int> GetLikeCount(int cheepId)
         return await db.GetLikeCount(cheepId);
     }
 
-    public async Task<bool> HasUserLikedCheep(int cheepId, string author)
+    public async Task<bool> HasUserLikedCheep(int cheepId, string username)
     {
-        return await db.HasUserLikedCheep(cheepId, author);
+        return await db.HasUserLikedCheep(cheepId, username);
     }
 }

Chirp/src/Chirp.Core/CustomException/UserDoesNotExist.cs

@@ -1,5 +1,8 @@
 namespace Chirp.Core.CustomException;
-
+/// <summary>
+/// Exception to be thrown if some User does not exist in the database
+/// </summary>
+/// <param name="message"></param>
 public class UserDoesNotExist(string message) : Exception(message)
 {
     public UserDoesNotExist() : this("User does not exist")

Chirp/src/Chirp.Core/DTO/AuthorDTO.cs

@@ -1,4 +1,7 @@
 namespace Chirp.Core.DTO;
+/// <summary>
+///  The AuthorDTO class, transfers Author information from the AuthorRepository to the UI
+/// </summary>
 
 public class AuthorDTO(string name, string email, byte[]? ProfileImage = null)
 {

Chirp/src/Chirp.Core/DTO/CheepDTO.cs

@@ -1,4 +1,7 @@
 namespace Chirp.Core.DTO;
+/// <summary>
+/// The CheepDTO class transfers information about Cheeps from the CheepRepository to the UI
+/// </summary>
 
 public class CheepDTO(int? id, string author, string message, long unixTimestamp)
 {

Chirp/src/Chirp.Core/DTO/CommentDTO.cs

@@ -1,5 +1,7 @@
 namespace Chirp.Core.DTO;
-
+/// <summary>
+/// The CommentDTO class transfers Comment data from RepositoryLayer to the UI
+/// </summary>
 public class CommentDTO(string author, int cheepId, string message, long unixTimestamp)
 {
     public string Author { get; set; } = author;

Chirp/src/Chirp.Core/DTO/LikeDTO.cs

@@ -1,5 +1,7 @@
 namespace Chirp.Core.DTO;
-
+/// <summary>
+/// The LikeDTO transfers data for which Author likes which Cheeps
+/// </summary>
 public class LikeDTO(string author, int cheepId, int? id = null)
 {
     public int? Id { get; set; } = id;