Merge pull request #50 from PinguApps/33-add-intellisense-comments

Added intellisense comments to everything public in all projects

Directory.Build.targets

@@ -3,6 +3,10 @@
     <!-- Add default suffix if there is no InternalsVisibleTo or InternalsVisibleToSuffix defined -->
     <ItemGroup Condition="@(InternalsVisibleToSuffix->Count()) == 0 AND @(InternalsVisibleTo->Count()) == 0">
       <InternalsVisibleToSuffix Include=".Tests" />
+
+      <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
+        <_Parameter1>DynamicProxyGenAssembly2</_Parameter1>
+      </AssemblyAttribute>
     </ItemGroup>
 
     <!-- Handle InternalsVisibleTo -->

src/PinguApps.Appwrite.Client/Clients/AccountClient.cs

@@ -8,6 +8,7 @@
 using PinguApps.Appwrite.Shared.Responses;
 
 namespace PinguApps.Appwrite.Client;
+
 public class AccountClient : IAccountClient, ISessionAware
 {
     private readonly IAccountApi _accountApi;
@@ -31,6 +32,7 @@ public AccountClient(IAccountApi accountApi)
         return _sessionAware.Session;
     }
 
+    /// <inheritdoc/>
     public async Task<AppwriteResult<User>> Get()
     {
         try
@@ -46,6 +48,7 @@ public async Task<AppwriteResult<User>> Get()
         }
     }
 
+    /// <inheritdoc/>
     public async Task<AppwriteResult<User>> Create(CreateAccountRequest request)
     {
         try

src/PinguApps.Appwrite.Client/Clients/AppwriteClient.cs

@@ -1,8 +1,9 @@
 using PinguApps.Appwrite.Client.Clients;
 
 namespace PinguApps.Appwrite.Client;
-public class AppwriteClient : IAppwriteClient
+public class AppwriteClient : IAppwriteClient, ISessionAware
 {
+    /// <inheritdoc/>
     public IAccountClient Account { get; }
 
     public AppwriteClient(IAccountClient accountClient)
@@ -13,6 +14,7 @@ public AppwriteClient(IAccountClient accountClient)
     string? ISessionAware.Session { get; set; }
 
     ISessionAware? _sessionAware;
+    /// <inheritdoc/>
     public string? Session => GetSession();
     private string? GetSession()
     {
@@ -24,6 +26,7 @@ public AppwriteClient(IAccountClient accountClient)
         return _sessionAware.Session;
     }
 
+    /// <inheritdoc/>
     public void SetSession(string? session)
     {
         (this as ISessionAware).UpdateSession(session);

src/PinguApps.Appwrite.Client/Clients/IAccountClient.cs

@@ -4,8 +4,27 @@
 using PinguApps.Appwrite.Shared.Responses;
 
 namespace PinguApps.Appwrite.Client;
+
+/// <summary>
+/// <para>The Account service allows you to authenticate and manage a user account. You can use the account service to update user information, retrieve the user sessions across different devices, and fetch the user security logs with his or her recent activity.</para>
+/// <para>Register new user accounts with the Create Account, Create Magic URL session, or Create Phone session endpoint.You can authenticate the user account by using multiple sign-in methods available.Once the user is authenticated, a new session object will be created to allow the user to access his or her private data and settings.</para>
+/// <para>This service also exposes an endpoint to save and read the user preferences as a key-value object. This feature is handy if you want to allow extra customization in your app.Common usage for this feature may include saving the user's preferred locale, timezone, or custom app theme.</para>
+/// <para><see href="https://appwrite.io/docs/references/1.5.x/client-rest/account">Appwrite Docs</see></para>
+/// </summary>
 public interface IAccountClient
 {
+    /// <summary>
+    /// Use this endpoint to allow a new user to register a new account in your project. After the user registration completes successfully, you can use the /account/verfication route to start verifying the user email address. To allow the new user to login to their new account, you need to create a new account session.
+    /// <para><see href="https://appwrite.io/docs/references/1.5.x/client-rest/account#create">Appwrite Docs</see></para>
+    /// </summary>
+    /// <param name="request">The request content</param>
+    /// <returns>The created user</returns>
     Task<AppwriteResult<User>> Create(CreateAccountRequest request);
+
+    /// <summary>
+    /// Get the currently logged in user.
+    /// <para><see href="https://appwrite.io/docs/references/1.5.x/client-rest/account#get">Appwrite Docs</see></para>
+    /// </summary>
+    /// <returns>The user</returns>
     Task<AppwriteResult<User>> Get();
 }

src/PinguApps.Appwrite.Client/Clients/IAppwriteClient.cs

@@ -1,10 +1,26 @@
-using PinguApps.Appwrite.Client.Clients;
+namespace PinguApps.Appwrite.Client;
 
-namespace PinguApps.Appwrite.Client;
-
-public interface IAppwriteClient : ISessionAware
+/// <summary>
+/// The root of the Client SDK. Access all API sections from here
+/// </summary>
+public interface IAppwriteClient
 {
+    /// <summary>
+    /// <para>The Account service allows you to authenticate and manage a user account. You can use the account service to update user information, retrieve the user sessions across different devices, and fetch the user security logs with his or her recent activity.</para>
+    /// <para>Register new user accounts with the Create Account, Create Magic URL session, or Create Phone session endpoint.You can authenticate the user account by using multiple sign-in methods available.Once the user is authenticated, a new session object will be created to allow the user to access his or her private data and settings.</para>
+    /// <para>This service also exposes an endpoint to save and read the user preferences as a key-value object. This feature is handy if you want to allow extra customization in your app.Common usage for this feature may include saving the user's preferred locale, timezone, or custom app theme.</para>
+    /// <para><see href="https://appwrite.io/docs/references/1.5.x/client-rest/account">Appwrite Docs</see></para>
+    /// </summary>
     IAccountClient Account { get; }
 
+    /// <summary>
+    /// Set the session of the logged in user
+    /// </summary>
+    /// <param name="session">The session token</param>
     void SetSession(string? session);
+
+    /// <summary>
+    /// The sessio of the currently logged in user
+    /// </summary>
+    string? Session { get; }
 }

src/PinguApps.Appwrite.Client/Clients/ISessionAware.cs

@@ -1,6 +1,8 @@
 namespace PinguApps.Appwrite.Client.Clients;
-public interface ISessionAware
+
+internal interface ISessionAware
 {
     public string? Session { get; protected set; }
+
     public void UpdateSession(string? session) => Session = session;
 }

src/PinguApps.Appwrite.Client/ServiceCollectionExtensions.cs

@@ -5,8 +5,20 @@
 using Refit;
 
 namespace PinguApps.Appwrite.Client;
+
+/// <summary>
+/// Provides extenions to IServiceCollection, to enable adding the SDK to your DI container
+/// </summary>
 public static class ServiceCollectionExtensions
 {
+    /// <summary>
+    /// Adds all necessary components for the Client SDK to work as a singleton. Best used on client-side
+    /// </summary>
+    /// <param name="services">The service collection to add to</param>
+    /// <param name="projectId">Your Appwrite Project ID</param>
+    /// <param name="endpoint">Your Appwrite Endpoint. Defaults to the cloud endpoint.</param>
+    /// <param name="refitSettings">Custom refit settings to customise the SDK.</param>
+    /// <returns>The service collection, enabling chaining</returns>
     public static IServiceCollection AddAppwriteClient(this IServiceCollection services, string projectId, string endpoint = "https://cloud.appwrite.io/v1", RefitSettings? refitSettings = null)
     {
         services.AddSingleton(sp => new HeaderHandler(projectId));
@@ -21,6 +33,14 @@ public static IServiceCollection AddAppwriteClient(this IServiceCollection servi
         return services;
     }
 
+    /// <summary>
+    /// Adds all necessary components for the Client SDK in a transient state. Best used on server-side to perform client SDK abilities on behalf of users
+    /// </summary>
+    /// <param name="services">The service collection to add to</param>
+    /// <param name="projectId">Your Appwrite Project ID</param>
+    /// <param name="endpoint">Your Appwrite Endpoint. Defaults to the could endpoint.</param>
+    /// <param name="refitSettings">Custom refit settings to customise the SDK.</param>
+    /// <returns>The service collection, enabling chaining</returns>
     public static IServiceCollection AddAppwriteClientForServer(this IServiceCollection services, string projectId, string endpoint = "https://cloud.appwrite.io/v1", RefitSettings? refitSettings = null)
     {
         services.AddSingleton(sp => new HeaderHandler(projectId));

src/PinguApps.Appwrite.Common/AppwriteError.cs

@@ -1,6 +1,14 @@
 using System.Text.Json.Serialization;
 
 namespace PinguApps.Appwrite.Shared;
+
+/// <summary>
+/// An error thrown from Appwrite
+/// </summary>
+/// <param name="Message">The message returned from Appwrite</param>
+/// <param name="Code">Http Status Code of the response</param>
+/// <param name="Type">The type of error thrown</param>
+/// <param name="Version">The version of Appwrite throwing the error</param>
 public record AppwriteError(
     [property: JsonPropertyName("message")] string Message,
     [property: JsonPropertyName("code")] int Code,

src/PinguApps.Appwrite.Common/AppwriteResult.cs

@@ -1,16 +1,40 @@
 using OneOf;
 
 namespace PinguApps.Appwrite.Shared;
+
+/// <summary>
+/// The result of all API calls
+/// </summary>
+/// <typeparam name="TResult">the type of response expected on success</typeparam>
 public class AppwriteResult<TResult>
 {
     public AppwriteResult(OneOf<TResult, AppwriteError, InternalError> result)
     {
         Result = result;
     }
 
+    /// <summary>
+    /// The result of making the API call. Can be <see cref="TResult"/>, <see cref="AppwriteError"/> or <see cref="InternalError"/> depending on what happened
+    /// </summary>
     public OneOf<TResult, AppwriteError, InternalError> Result { get; }
+
+    /// <summary>
+    /// Indicates the API call was successful
+    /// </summary>
     public bool Success => Result.IsT0;
+
+    /// <summary>
+    /// Indicates there is an error
+    /// </summary>
     public bool IsError => Result.IsT1 || Result.IsT2;
+
+    /// <summary>
+    /// Indicates that there was an error thrown within Appwrite
+    /// </summary>
     public bool IsAppwriteError => Result.IsT1;
+
+    /// <summary>
+    /// Indicates that there was an error thrown within the SDK
+    /// </summary>
     public bool IsInternalError => Result.IsT2;
 }

src/PinguApps.Appwrite.Common/Enums/TargetProviderType.cs

@@ -1,12 +1,25 @@
 using System.Runtime.Serialization;
 
 namespace PinguApps.Appwrite.Shared.Enums;
+
+/// <summary>
+/// The type of target
+/// </summary>
 public enum TargetProviderType
 {
+    /// <summary>
+    /// Email
+    /// </summary>
     [EnumMember(Value = "email")]
     Email,
+    /// <summary>
+    /// Sms
+    /// </summary>
     [EnumMember(Value = "sms")]
     Sms,
+    /// <summary>
+    /// Push
+    /// </summary>
     [EnumMember(Value = "push")]
     Push
 }

src/PinguApps.Appwrite.Common/InternalError.cs

@@ -1,4 +1,9 @@
 namespace PinguApps.Appwrite.Shared;
+
+/// <summary>
+/// An internal error, indicating a fault within the SDK rather than Appwrite
+/// </summary>
+/// <param name="Message">The message of any thrown exception</param>
 public record InternalError(
     string Message
 );

src/PinguApps.Appwrite.Common/Requests/CreateAccountRequest.cs

@@ -2,17 +2,33 @@
 using PinguApps.Appwrite.Shared.Utils;
 
 namespace PinguApps.Appwrite.Shared.Requests;
+
+/// <summary>
+/// The request for creating an account
+/// </summary>
 public class CreateAccountRequest
 {
+    /// <summary>
+    /// User ID. Choose a custom ID or generate a random ID with <see cref="IdUtils.GenerateUniqueId(int)"/>. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars
+    /// </summary>
     [JsonPropertyName("userId")]
     public string UserId { get; set; } = IdUtils.GenerateUniqueId();
 
+    /// <summary>
+    /// User email
+    /// </summary>
     [JsonPropertyName("email")]
     public string Email { get; set; } = string.Empty;
 
+    /// <summary>
+    /// New user password. Must be between 8 and 256 chars
+    /// </summary>
     [JsonPropertyName("password")]
     public string Password { get; set; } = string.Empty;
 
+    /// <summary>
+    /// User name. Max length: 128 chars
+    /// </summary>
     [JsonPropertyName("name")]
     public string? Name { get; set; }
 }

src/PinguApps.Appwrite.Common/Responses/HashOptions.cs

@@ -1,6 +1,14 @@
 using System.Text.Json.Serialization;
 
 namespace PinguApps.Appwrite.Shared.Responses;
+
+/// <summary>
+/// Password hashing algorithm information
+/// </summary>
+/// <param name="Type">The hashing algorithm</param>
+/// <param name="MemoryCost">The memory cost of the hash</param>
+/// <param name="TimeCost">The time cost of the hash</param>
+/// <param name="Threads">The threads used</param>
 public record HashOptions(
     [property: JsonPropertyName("type")] string Type,
     [property: JsonPropertyName("memoryCost")] long MemoryCost,

src/PinguApps.Appwrite.Common/Responses/Target.cs

@@ -3,6 +3,17 @@
 using PinguApps.Appwrite.Shared.Enums;
 
 namespace PinguApps.Appwrite.Shared.Responses;
+/// <summary>
+/// A user-owned message receiver. A single user may have multiple e.g. emails, phones, and a browser. Each target is registered with a single provider.
+/// </summary>
+/// <param name="Id">Target ID</param>
+/// <param name="CreatedAt">Target creation time in ISO 8601 format</param>
+/// <param name="UpdatedAt">Target update date in ISO 8601 format</param>
+/// <param name="Name">Target Name</param>
+/// <param name="UserId">User ID</param>
+/// <param name="ProviderId">Provider ID</param>
+/// <param name="ProviderType">The target provider type. Can be one of the following: `email`, `sms` or `push`</param>
+/// <param name="Identifier">The target identifier</param>
 public record Target(
     [property: JsonPropertyName("$id")] string Id,
     [property: JsonPropertyName("$createdAt")] DateTime CreatedAt,

src/PinguApps.Appwrite.Common/Responses/User.cs

@@ -3,6 +3,30 @@
 using System.Text.Json.Serialization;
 
 namespace PinguApps.Appwrite.Shared.Responses;
+
+/// <summary>
+/// An Appwrite User object
+/// </summary>
+/// <param name="Id">User ID</param>
+/// <param name="CreatedAt">User creation date in ISO 8601 format</param>
+/// <param name="UpdatedAt">User update date in ISO 8601 format</param>
+/// <param name="Name">User name</param>
+/// <param name="Password">Hashed user password</param>
+/// <param name="Hash">Password hashing algorithm</param>
+/// <param name="HashOptions">Password hashing algorithm configuration. Can be one of:
+///     <para>AlgoArgon2 model, AlgoScrypt model, AlgoScryptModified model, AlgoBcrypt model, AlgoPHPass model, AlgoSHA model, AlgoMD5 model</para></param>
+/// <param name="Registration">User registration date in ISO 8601 format</param>
+/// <param name="Status">User status. Pass `true` for enabled and `false` for disabled</param>
+/// <param name="Labels">Labels for the user</param>
+/// <param name="PasswordUpdate">Password update time in ISO 8601 format</param>
+/// <param name="Email">User email address</param>
+/// <param name="Phone">User phone number in E.164 format</param>
+/// <param name="EmailVerification">Email verification status</param>
+/// <param name="PhoneVerification">Phone verification status</param>
+/// <param name="Mfa">Multi factor authentication status</param>
+/// <param name="Prefs">User preferences as a key-value object</param>
+/// <param name="Targets">A user-owned message receiver. A single user may have multiple e.g. emails, phones, and a browser. Each target is registered with a single provider. Can be one of: <see cref="Target"/></param>
+/// <param name="AccessedAt">Most recent access date in ISO 8601 format. This attribute is only updated again after 24 hours</param>
 public record User(
     [property: JsonPropertyName("$id")] string Id,
     [property: JsonPropertyName("$createdAt")] DateTime CreatedAt,

src/PinguApps.Appwrite.Common/Utils/IdUtils.cs

@@ -2,10 +2,18 @@
 using System.Linq;
 
 namespace PinguApps.Appwrite.Shared.Utils;
+
+/// <summary>
+/// Utilities for Appwrite Id properties
+/// </summary>
 public static class IdUtils
 {
-    private static readonly Random _random = new Random();
+    private static readonly Random _random = new();
 
+    /// <summary>
+    /// Generates a Hex Timestamp, used in Id's
+    /// </summary>
+    /// <returns>a string of the hex timestamp for UTC now</returns>
     public static string GetHexTimestamp()
     {
         var dt = DateTimeOffset.UtcNow;
@@ -15,6 +23,11 @@ public static string GetHexTimestamp()
         return sec.ToString("x") + msec.ToString("x").PadLeft(5, '0');
     }
 
+    /// <summary>
+    /// Generates a unique Id under the same rules that Appwrite uses to generate unique Ids
+    /// </summary>
+    /// <param name="padding">The padding to use - defaults to 7</param>
+    /// <returns>A unique Id, in line with Appwrite Id generation rules</returns>
     public static string GenerateUniqueId(int padding = 7)
     {
         var baseId = GetHexTimestamp();