Merge pull request #721 from Im-Madhur-Gupta/docs-web-template

Add inline doc comments to the Web SDK template

Author: lohanidamodar

templates/web/src/client.ts.twig

@@ -1,83 +1,275 @@
 import { Models } from './models';
 import { Service } from './service';
 
+/**
+ * Payload type representing a key-value pair with string keys and any values.
+ */
 type Payload = {
     [key: string]: any;
 }
 
+/**
+ * Headers type representing a key-value pair with string keys and string values.
+ */
 type Headers = {
     [key: string]: string;
 }
 
+/**
+ * Realtime response structure with different types.
+ */
 type RealtimeResponse = {
+    /**
+     * Type of the response: 'error', 'event', 'connected', or 'response'.
+     */
     type: 'error' | 'event' | 'connected' | 'response';
+
+    /**
+     * Data associated with the response based on the response type.
+     */
     data: RealtimeResponseAuthenticated | RealtimeResponseConnected | RealtimeResponseError | RealtimeResponseEvent<unknown>;
 }
 
+/**
+ * Realtime request structure for authentication.
+ */
 type RealtimeRequest = {
+    /**
+     * Type of the request: 'authentication'.
+     */
     type: 'authentication';
+
+    /**
+     * Data required for authentication.
+     */
     data: RealtimeRequestAuthenticate;
 }
 
+/**
+ * Realtime event response structure with generic payload type.
+ */
 export type RealtimeResponseEvent<T extends unknown> = {
+    /**
+     * List of event names associated with the response.
+     */
     events: string[];
+
+    /**
+     * List of channel names associated with the response.
+     */
     channels: string[];
+
+    /**
+     * Timestamp indicating the time of the event.
+     */
     timestamp: number;
+
+    /**
+     * Payload containing event-specific data.
+     */
     payload: T;
 }
 
+/**
+ * Realtime response structure for errors.
+ */
 type RealtimeResponseError = {
+    /**
+     * Numeric error code indicating the type of error.
+     */
     code: number;
+
+    /**
+     * Error message describing the encountered error.
+     */
     message: string;
 }
 
+/**
+ * Realtime response structure for a successful connection.
+ */
 type RealtimeResponseConnected = {
+    /**
+     * List of channels the user is connected to.
+     */
     channels: string[];
+
+    /**
+     * User object representing the connected user (optional).
+     */
     user?: object;
 }
 
+/**
+ * Realtime response structure for authenticated connections.
+ */
 type RealtimeResponseAuthenticated = {
+    /**
+     * Destination channel for the response.
+     */
     to: string;
+
+    /**
+     * Boolean indicating the success of the authentication process.
+     */
     success: boolean;
+
+    /**
+     * User object representing the authenticated user.
+     */
     user: object;
 }
 
+/**
+ * Realtime request structure for authentication.
+ */
 type RealtimeRequestAuthenticate = {
+    /**
+     * Session identifier for authentication.
+     */
     session: string;
 }
 
+/**
+ * Realtime interface representing the structure of a realtime communication object.
+ */
 type Realtime = {
+    /**
+     * WebSocket instance for realtime communication.
+     */
     socket?: WebSocket;
+
+    /**
+     * Timeout duration for communication operations.
+     */
     timeout?: number;
+
+    /**
+     * URL for establishing the WebSocket connection.
+     */
     url?: string;
+
+    /**
+     * Last received message from the realtime server.
+     */
     lastMessage?: RealtimeResponse;
+
+    /**
+     * Set of channel names the client is subscribed to.
+     */
     channels: Set<string>;
+
+    /**
+     * Map of subscriptions containing channel names and corresponding callback functions.
+     */
     subscriptions: Map<number, {
         channels: string[];
         callback: (payload: RealtimeResponseEvent<any>) => void
     }>;
+
+    /**
+     * Counter for managing subscriptions.
+     */
     subscriptionsCounter: number;
+
+    /**
+     * Boolean indicating whether automatic reconnection is enabled.
+     */
     reconnect: boolean;
+
+    /**
+     * Number of reconnection attempts made.
+     */
     reconnectAttempts: number;
+
+    /**
+     * Function to get the timeout duration for communication operations.
+     */
     getTimeout: () => number;
+
+    /**
+     * Function to establish a WebSocket connection.
+     */
     connect: () => void;
+
+    /**
+     * Function to create a new WebSocket instance.
+     */
     createSocket: () => void;
+
+    /**
+     * Function to clean up resources associated with specified channels.
+     *
+     * @param {string[]} channels - List of channel names to clean up.
+     */
     cleanUp: (channels: string[]) => void;
+
+    /**
+     * Function to handle incoming messages from the WebSocket connection.
+     *
+     * @param {MessageEvent} event - Event containing the received message.
+     */
     onMessage: (event: MessageEvent) => void;
 }
 
+/**
+ * Type representing upload progress information.
+ */
 export type UploadProgress = {
+    /**
+     * Identifier for the upload progress.
+     */
     $id: string;
+
+    /**
+     * Current progress of the upload (in percentage).
+     */
     progress: number;
+
+    /**
+     * Total size uploaded (in bytes) during the upload process.
+     */
     sizeUploaded: number;
+
+    /**
+     * Total number of chunks that need to be uploaded.
+     */
     chunksTotal: number;
+
+    /**
+     * Number of chunks that have been successfully uploaded.
+     */
     chunksUploaded: number;
 }
 
+/**
+ * Exception thrown by the {{language.params.packageName}} package
+ */
 class {{spec.title | caseUcfirst}}Exception extends Error {
+    /**
+     * The error code associated with the exception.
+     */
     code: number;
+
+    /**
+     * The response string associated with the exception.
+     */
     response: string;
+
+    /**
+     * Error type.
+     * See [Error Types]({{sdk.url}}/docs/response-codes#errorTypes) for more information.
+     */
     type: string;
+
+    /**
+     * Initializes a {{spec.title | caseUcfirst}} Exception.
+     *
+     * @param {string} message - The error message.
+     * @param {number} code - The error code. Default is 0.
+     * @param {string} type - The error type. Default is an empty string.
+     * @param {string} response - The response string. Default is an empty string.
+     */
     constructor(message: string, code: number = 0, type: string = '', response: string = '') {
         super(message);
         this.name = '{{spec.title | caseUcfirst}}Exception';
@@ -88,14 +280,24 @@ class {{spec.title | caseUcfirst}}Exception extends Error {
     }
 }
 
+/**
+ * Client that handles requests to {{spec.title | caseUcfirst}}
+ */
 class Client {
+    /**
+     * Holds configuration such as project.
+     */
     config = {
         endpoint: '{{ spec.endpoint }}',
         endpointRealtime: '',
 {% for header in spec.global.headers %}
         {{ header.key | caseLower }}: '',
 {% endfor %}
     };
+
+    /**
+     * Custom headers for API requests.
+     */
     headers: Headers = {
         'x-sdk-name': '{{ sdk.name }}',
         'x-sdk-platform': '{{ sdk.platform }}',
@@ -338,6 +540,19 @@ class Client {
         }
     }
 
+    /**
+     * Call API endpoint with the specified method, URL, headers, and parameters.
+     *
+     * @param {string} method - HTTP method (e.g., 'GET', 'POST', 'PUT', 'DELETE').
+     * @param {URL} url - The URL of the API endpoint.
+     * @param {Headers} headers - Custom headers for the API request.
+     * @param {Payload} params - Request parameters.
+     * @returns {Promise<any>} - A promise that resolves with the response data.
+     * 
+     * @typedef {Object} Payload - Request payload data.
+     * @property {string} key - The key.
+     * @property {string} value - The value.
+     */
     async call(method: string, url: URL, headers: Headers = {}, params: Payload = {}): Promise<any> {
         method = method.toUpperCase();
 

templates/web/src/id.ts.twig

@@ -1,6 +1,13 @@
+/**
+ * Helper class to generate ID strings for resources.
+ */
 export class ID {
-    // Generate an hex ID based on timestamp
-    // Recreated from https://www.php.net/manual/en/function.uniqid.php
+    /**
+     * Generate an hex ID based on timestamp.
+     * Recreated from https://www.php.net/manual/en/function.uniqid.php
+     *
+     * @returns {string}
+     */
     static #hexTimestamp(): string {
         const now = new Date();
         const sec = Math.floor(now.getTime() / 1000);
@@ -11,10 +18,22 @@ export class ID {
         return hexTimestamp;
     }
 
+    /**
+     * Uses the provided ID as the ID for the resource.
+     *
+     * @param {string} id
+     * @returns {string}
+     */
     public static custom(id: string): string {
         return id
     }
 
+    /**
+     * Have Appwrite generate a unique ID for you.
+     * 
+     * @param {number} padding. Default is 7.
+     * @returns {string}
+     */
     public static unique(padding: number = 7): string {
         // Generate a unique ID with padding to have a longer ID
         const baseId = ID.#hexTimestamp();

templates/web/src/index.ts.twig

@@ -1,3 +1,10 @@
+/**
+ * {{spec.title | caseUcfirst}} {{sdk.name}} SDK
+ *
+ * This SDK is compatible with Appwrite server version {{spec.version | split('.') | slice(0,2) | join('.') ~ '.x' }}. 
+ * For older versions, please check
+ * [previous releases](https://github.com/{{sdk.gitUserName}}/{{sdk.gitRepoName}}/releases).
+ */
 export { Client, Query, {{spec.title | caseUcfirst}}Exception } from './client';
 {% for service in spec.services %}
 export { {{service.name | caseUcfirst}} } from './services/{{service.name | caseDash}}';

templates/web/src/models.ts.twig

@@ -1,3 +1,6 @@
+/**
+ * {{spec.title | caseUcfirst}} Models
+ */
 export namespace Models {
 {% for definition in spec.definitions %}
     /**