More docs for https://github.com/oqtane/oqtane.framework/issues/1382 - should not affect any code

Oqtane.Client/Services/Interfaces/IAliasService.cs

@@ -6,7 +6,7 @@ using System.Threading.Tasks;
 namespace Oqtane.Services
 {
     /// <summary>
-    /// Retrieve and store <see cref="Oqtane.Models.Alias"/> information.
+    /// Service to retrieve and store <see cref="Alias"/> information.
     /// </summary>
     public interface IAliasService
     {

Oqtane.Client/Services/Interfaces/IFileService.cs

@@ -4,19 +4,103 @@ using System.Threading.Tasks;
 
 namespace Oqtane.Services
 {
+    /// <summary>
+    /// Service to get / create / upload / download files.
+    /// </summary>
     public interface IFileService
     {
+        /// <summary>
+        /// Get all <see cref="File"/>s in the specified Folder
+        /// </summary>
+        /// <param name="folderId">The folder ID</param>
+        /// <returns></returns>
         Task<List<File>> GetFilesAsync(int folderId);
+
+        /// <summary>
+        /// Get all <see cref="File"/>s in the specified folder. 
+        /// </summary>
+        /// <param name="folder">
+        /// The folder path relative to where the files are stored.
+        /// TODO: todoc verify exactly from where the folder path must start
+        /// </param>
+        /// <returns></returns>
         Task<List<File>> GetFilesAsync(string folder);
+
+        /// <summary>
+        /// Get one <see cref="File"/>
+        /// </summary>
+        /// <param name="fileId"></param>
+        /// <returns></returns>
         Task<File> GetFileAsync(int fileId);
+
+        /// <summary>
+        /// Add / store a <see cref="File"/> record.
+        /// This does not contain the file contents. 
+        /// </summary>
+        /// <param name="file"></param>
+        /// <returns></returns>
         Task<File> AddFileAsync(File file);
+
+        /// <summary>
+        /// Update a <see cref="File"/> record.
+        /// Use this for rename a file or change some attributes. 
+        /// This does not contain the file contents. 
+        /// </summary>
+        /// <param name="file"></param>
+        /// <returns></returns>
         Task<File> UpdateFileAsync(File file);
+
+        /// <summary>
+        /// Delete a <see cref="File"/>
+        /// </summary>
+        /// <param name="fileId"></param>
+        /// <returns></returns>
         Task DeleteFileAsync(int fileId);
+
+        /// <summary>
+        /// Upload a file from a URL to a <see cref="Folder"/>
+        /// </summary>
+        /// <param name="url"></param>
+        /// <param name="folderId"></param>
+        /// <returns></returns>
         Task<File> UploadFileAsync(string url, int folderId);
+
+        /// <summary>
+        /// Upload one or more files.
+        /// </summary>
+        /// <param name="folderId">Target <see cref="Folder"/></param>
+        /// <param name="files">The files to upload, serialized as a string.</param>
+        /// <param name="fileUploadName">A task-identifier, to ensure communication about this upload.</param>
+        /// <returns></returns>
         Task<string> UploadFilesAsync(int folderId, string[] files, string fileUploadName);
+
+
+        /// <summary>
+        /// Upload one or more files.
+        /// </summary>
+        /// <param name="folder">Target <see cref="Folder"/>
+        /// TODO: todoc verify exactly from where the folder path must start
+        /// </param>
+        /// <param name="files">The files to upload, serialized as a string.</param>
+        /// <param name="fileUploadName">A task-identifier, to ensure communication about this upload.</param>
+        /// <returns></returns>
         Task<string> UploadFilesAsync(string folder, string[] files, string fileUploadName);
+
+        /// <summary>
+        /// Get / download a file (the body).
+        /// </summary>
+        /// <param name="fileId">Reference to a <see cref="File"/></param>
+        /// <returns>The bytes of the file</returns>
         Task<byte[]> DownloadFileAsync(int fileId);
 
+        /// <summary>
+        /// Retrieve a list of files from a <see cref="Site"/> and <see cref="Folder"/>
+        /// </summary>
+        /// <param name="siteId">Reference to the <see cref="Site"/></param>
+        /// <param name="folderPath">Path of the folder
+        /// TODO: todoc verify exactly from where the folder path must start
+        /// </param>
+        /// <returns></returns>
         Task<List<File>> GetFilesAsync(int siteId, string folderPath);
     }
 }

Oqtane.Client/Services/Interfaces/IFolderService.cs

@@ -1,18 +1,68 @@
-using Oqtane.Models;
+using Oqtane.Models;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Threading.Tasks;
 
 namespace Oqtane.Services
 {
+    /// <summary>
+    /// Service to get / create / modify <see cref="Folder"/> objects.
+    /// </summary>
     public interface IFolderService
     {
+        /// <summary>
+        /// Retrieve root folders of a <see cref="Site"/>
+        /// </summary>
+        /// <param name="siteId"></param>
+        /// <returns></returns>
         Task<List<Folder>> GetFoldersAsync(int siteId);
+
+        /// <summary>
+        /// Retrieve the information of one <see cref="Folder"/>
+        /// </summary>
+        /// <param name="folderId"></param>
+        /// <returns></returns>
         Task<Folder> GetFolderAsync(int folderId);
+
+        /// <summary>
+        /// Create one Folder using a <see cref="Folder"/> object. 
+        /// </summary>
+        /// <param name="folder"></param>
+        /// <returns></returns>
         Task<Folder> AddFolderAsync(Folder folder);
+
+        /// <summary>
+        /// Update the information about a <see cref="Folder"/>
+        /// Use this to rename the folder etc.
+        /// </summary>
+        /// <param name="folder"></param>
+        /// <returns></returns>
         Task<Folder> UpdateFolderAsync(Folder folder);
+
+        /// <summary>
+        /// Update the internal Folder-Order within the list of Folders.
+        /// </summary>
+        /// <param name="siteId">Reference to the <see cref="Site"/></param>
+        /// <param name="folderId">Reference to a <see cref="Folder"/> for the security check</param>
+        /// <param name="parentId">Reference to the Parent <see cref="Folder"/> or null - this Folders children will be re-sorted.</param>
+        /// <returns></returns>
         Task UpdateFolderOrderAsync(int siteId, int folderId, int? parentId);
+
+        /// <summary>
+        /// Delete a <see cref="Folder"/>
+        /// </summary>
+        /// <param name="folderId">Reference to a <see cref="Folder"/></param>
+        /// <returns></returns>
         Task DeleteFolderAsync(int folderId);
+
+        /// <summary>
+        /// Get a <see cref="Folder"/> of a <see cref="Site"/> based on the path.
+        /// </summary>
+        /// <param name="siteId">Reference to the <see cref="Site"/></param>
+        /// <param name="folderPath">Path of the folder
+        /// TODO: todoc verify exactly from where the folder path must start
+        /// </param>
+        /// <returns></returns>
         Task<Folder> GetFolderAsync(int siteId, [NotNull]string folderPath);
     }
 }

Oqtane.Client/Services/Interfaces/IRoleService.cs

@@ -4,18 +4,54 @@ using System.Threading.Tasks;
 
 namespace Oqtane.Services
 {
+    /// <summary>
+    /// Service to manage <see cref="Role"/>s on a <see cref="Site"/>
+    /// </summary>
     public interface IRoleService
     {
+        /// <summary>
+        /// Get all <see cref="Role"/>s of this <see cref="Site"/>.
+        ///
+        /// Will exclude global roles which are for all sites. To get those as well, use the overload <see cref="GetRolesAsync(int, bool)"/>
+        /// </summary>
+        /// <param name="siteId">ID-reference of a <see cref="Site"/></param>
+        /// <returns></returns>
         Task<List<Role>> GetRolesAsync(int siteId);
 
+        /// <summary>
+        /// Get roles of the <see cref="Site"/> and optionally include global Roles.
+        /// </summary>
+        /// <param name="siteId">ID-reference to a <see cref="Site"/></param>
+        /// <param name="includeGlobalRoles">True if it should also include global roles. False will return the same data as just calling <see cref="GetRolesAsync(int)"/></param>
+        /// <returns></returns>
         Task<List<Role>> GetRolesAsync(int siteId, bool includeGlobalRoles);
 
+        /// <summary>
+        /// Get one specific <see cref="Role"/>
+        /// </summary>
+        /// <param name="roleId">ID-reference of a <see cref="Role"/></param>
+        /// <returns></returns>
         Task<Role> GetRoleAsync(int roleId);
 
+        /// <summary>
+        /// Add / save a new <see cref="Role"/> to the database.
+        /// </summary>
+        /// <param name="role"></param>
+        /// <returns></returns>
         Task<Role> AddRoleAsync(Role role);
 
+        /// <summary>
+        /// Update a <see cref="Role"/> in the database.
+        /// </summary>
+        /// <param name="role"></param>
+        /// <returns></returns>
         Task<Role> UpdateRoleAsync(Role role);
 
+        /// <summary>
+        /// Delete / mark-as-deleted a <see cref="Role"/> in the database.
+        /// </summary>
+        /// <param name="roleId">ID-reference of a <see cref="Role"/></param>
+        /// <returns></returns>
         Task DeleteRoleAsync(int roleId);
     }
 }

Oqtane.Client/Services/Interfaces/ITenantService.cs

@@ -1,19 +1,46 @@
-using Oqtane.Models;
+using Oqtane.Models;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
 namespace Oqtane.Services
 {
+    /// <summary>
+    /// Service to manage <see cref="Tenant"/>s on the Oqtane installation.
+    /// </summary>
     public interface ITenantService
     {
+        /// <summary>
+        /// Get all <see cref="Tenant"/>s
+        /// </summary>
+        /// <returns></returns>
         Task<List<Tenant>> GetTenantsAsync();
 
+        /// <summary>
+        /// Get one specific <see cref="Tenant"/>
+        /// </summary>
+        /// <param name="tenantId">ID-reference of the <see cref="Tenant"/></param>
+        /// <returns></returns>
         Task<Tenant> GetTenantAsync(int tenantId);
 
+        /// <summary>
+        /// Add / save another <see cref="Tenant"/> to the database
+        /// </summary>
+        /// <param name="tenant">A <see cref="Tenant"/> object containing the configuration</param>
+        /// <returns></returns>
         Task<Tenant> AddTenantAsync(Tenant tenant);
 
+        /// <summary>
+        /// Update the <see cref="Tenant"/> information in the database.
+        /// </summary>
+        /// <param name="tenant"></param>
+        /// <returns></returns>
         Task<Tenant> UpdateTenantAsync(Tenant tenant);
 
+        /// <summary>
+        /// Delete / remove a <see cref="Tenant"/>
+        /// </summary>
+        /// <param name="tenantId"></param>
+        /// <returns></returns>
         Task DeleteTenantAsync(int tenantId);
     }
 }

Oqtane.Client/Services/Interfaces/IUserRoleService.cs

@@ -1,15 +1,47 @@
-using Oqtane.Models;
+using Oqtane.Models;
 using System.Collections.Generic;
 using System.Threading.Tasks;
 
 namespace Oqtane.Services
 {
+    /// <summary>
+    /// Manage <see cref="Role"/>s assigned to a specific <see cref="User"/>
+    /// </summary>
     public interface IUserRoleService
     {
+        /// <summary>
+        /// Get all <see cref="UserRole"/>s on a <see cref="Site"/>
+        /// </summary>
+        /// <param name="siteId">ID-reference to a <see cref="Site"/></param>
+        /// <returns></returns>
         Task<List<UserRole>> GetUserRolesAsync(int siteId);
+
+        /// <summary>
+        /// Get one specific <see cref="UserRole"/>
+        /// </summary>
+        /// <param name="userRoleId">ID-reference to a <see cref="UserRole"/></param>
+        /// <returns></returns>
         Task<UserRole> GetUserRoleAsync(int userRoleId);
+
+        /// <summary>
+        /// Save a new <see cref="UserRole"/>
+        /// </summary>
+        /// <param name="userRole"></param>
+        /// <returns></returns>
         Task<UserRole> AddUserRoleAsync(UserRole userRole);
+
+        /// <summary>
+        /// Update a <see cref="UserRole"/> in the database
+        /// </summary>
+        /// <param name="userRole"></param>
+        /// <returns></returns>
         Task<UserRole> UpdateUserRoleAsync(UserRole userRole);
+
+        /// <summary>
+        /// Delete a <see cref="UserRole"/> in the database
+        /// </summary>
+        /// <param name="userRoleId"></param>
+        /// <returns></returns>
         Task DeleteUserRoleAsync(int userRoleId);
     }
 }

Oqtane.Client/Services/Interfaces/IUserService.cs

@@ -3,26 +3,90 @@ using System.Threading.Tasks;
 
 namespace Oqtane.Services
 {
+    /// <summary>
+    /// Manage (get / update) user information
+    /// </summary>
     public interface IUserService
     {
+        /// <summary>
+        /// Get a <see cref="User"/> of a specific site
+        /// </summary>
+        /// <param name="userId">ID of a <see cref="User"/></param>
+        /// <param name="siteId">ID of a <see cref="Site"/></param>
+        /// <returns></returns>
         Task<User> GetUserAsync(int userId, int siteId);
 
+        
+        /// <summary>
+        /// Get a <see cref="User"/> of a specific site
+        /// </summary>
+        /// <param name="username">Username / login of a <see cref="User"/></param>
+        /// <param name="siteId">ID of a <see cref="Site"/></param>
+        /// <returns></returns>
         Task<User> GetUserAsync(string username, int siteId);
 
+        /// <summary>
+        /// Save a user to the Database.
+        /// The <see cref="User"/> object contains all the information incl. what <see cref="Site"/> it belongs to. 
+        /// </summary>
+        /// <param name="user"></param>
+        /// <returns></returns>
         Task<User> AddUserAsync(User user);
 
+        /// <summary>
+        /// Update an existing user in the database.
+        /// </summary>
+        /// <param name="user"></param>
+        /// <returns></returns>
         Task<User> UpdateUserAsync(User user);
 
+        /// <summary>
+        /// Delete / remove a user in the database
+        /// </summary>
+        /// <param name="userId">ID-reference to the <see cref="User"/></param>
+        /// <param name="siteId">ID-reference to the <see cref="Site"/></param>
+        /// <returns></returns>
         Task DeleteUserAsync(int userId, int siteId);
 
+        /// <summary>
+        /// Will login the specified <see cref="User"/>.
+        /// 
+        /// Note that this will probably not be a real User, but a user object where the `Username` and `Password` have been filled.
+        /// </summary>
+        /// <param name="user">A <see cref="User"/> object which should have at least the <see cref="User.Username"/> and <see cref="User.Password"/> set.</param>
+        /// <param name="setCookie">Determines if the login should be stored in the cookie.</param>
+        /// <param name="isPersistent">Determines if the login should be persisted in the cookie for a long time.</param>
+        /// <returns></returns>
         Task<User> LoginUserAsync(User user, bool setCookie, bool isPersistent);
 
+        /// <summary>
+        /// Logout a <see cref="User"/>
+        /// </summary>
+        /// <param name="user"></param>
+        /// <returns></returns>
         Task LogoutUserAsync(User user);
 
+        /// <summary>
+        /// Update e-mail verification status of a user.
+        /// </summary>
+        /// <param name="user">The <see cref="User"/> we're verifying</param>
+        /// <param name="token">A Hash value in the URL which verifies this user got the e-mail (containing this token)</param>
+        /// <returns></returns>
         Task<User> VerifyEmailAsync(User user, string token);
 
+        /// <summary>
+        /// Trigger a forgot-password e-mail for this <see cref="User"/>. 
+        /// </summary>
+        /// <param name="user"></param>
+        /// <returns></returns>
         Task ForgotPasswordAsync(User user);
 
+        /// <summary>
+        /// Reset the password of this <see cref="User"/>
+        /// </summary>
+        /// <param name="user"></param>
+        /// <param name="token"></param>
+        /// <returns></returns>
         Task<User> ResetPasswordAsync(User user, string token);
     }
 }