refactor: add docblocks

Author: thetutlage

src/debug.ts

@@ -9,4 +9,15 @@
 
 import { debuglog } from 'node:util'
 
+/**
+ * Debug logger for the japa:plugin-adonisjs namespace.
+ *
+ * This logger is used to output debug information when the NODE_DEBUG environment
+ * variable includes 'japa:plugin-adonisjs'.
+ *
+ * @example
+ * ```js
+ * debug('extending @japa/api-client with adonisjs specific methods')
+ * ```
+ */
 export default debuglog('japa:plugin-adonisjs')

src/extend_api_client.ts

@@ -14,27 +14,51 @@ import './types/extended.js'
 import debug from './debug.ts'
 
 /**
- * Extending the "@japa/api-client" plugin with custom methods to
- * set cookies, session, csrf token and authenticated user.
+ * Extends the "@japa/api-client" plugin with AdonisJS-specific cookie methods.
+ *
+ * This function adds custom methods to the ApiClient for handling signed, encrypted,
+ * and plain cookies. It also sets up a cookie serializer to properly parse response
+ * cookies using the AdonisJS cookie client.
+ *
+ * @param cookieClient - The AdonisJS cookie client instance for cookie operations
+ *
+ * @example
+ * ```js
+ * extendApiClient(app.container.use('cookie'))
+ * ```
  */
 export function extendApiClient(cookieClient: CookieClient) {
   debug('extending @japa/api-client with adonisjs specific methods')
 
   /**
-   * Serializer for parsing response cookies
+   * Cookie serializer for handling AdonisJS cookies in API responses.
+   *
+   * Sets up methods to prepare cookies for requests and process cookies from responses.
+   * The prepare method returns values as-is since encryption/signing happens in the macro methods.
+   * The process method uses the AdonisJS cookie client to parse signed/encrypted cookies.
    */
   ApiClient.cookiesSerializer({
     /**
-     * The methods on the Request class encrypts and signs cookies.
-     * Therefore, the prepare method returns the value as it is
+     * Prepares cookie values for outgoing requests.
+     *
+     * Returns the value as-is since cookie encryption and signing is handled
+     * by the macro methods before reaching this serializer.
+     *
+     * @param _ - Cookie key (unused)
+     * @param value - Cookie value to prepare
      */
     prepare(_: string, value: any) {
       return value
     },
 
     /**
-     * Process the server response and convert cookie value to a
-     * plain string
+     * Processes cookies from server responses.
+     *
+     * Uses the AdonisJS cookie client to parse signed/encrypted cookies
+     * from server responses back to their original values.
+     *
+     * @param key - The cookie name
+     * @param value - The raw cookie value from server response
      */
     process(key: string, value: any) {
       if (!value) {

src/extend_browser_client.ts

@@ -16,8 +16,13 @@ import './types/extended.js'
 import debug from './debug.ts'
 
 /**
- * Normalizes the cookies options to use the default domain
- * and path
+ * Normalizes cookie options by setting default domain and path values.
+ *
+ * This function ensures cookies have consistent domain and path settings
+ * by applying defaults when not explicitly provided.
+ *
+ * @param defaultDomain - The default domain to use for cookies
+ * @param options - Optional cookie options to merge with defaults
  */
 function normalizeCookieOptions(defaultDomain?: string, options?: CookieOptions): CookieOptions {
   return Object.assign(
@@ -30,8 +35,13 @@ function normalizeCookieOptions(defaultDomain?: string, options?: CookieOptions)
 }
 
 /**
- * Mimicing the behavior of https://github.com/jshttp/cookie/blob/master/index.js
- * package used by AdonisJS to decode response cookies.
+ * Safely decodes URL-encoded cookie values.
+ *
+ * Mimics the behavior of the jshttp/cookie package used by AdonisJS.
+ * Attempts to decode URL-encoded values but returns the original value
+ * if decoding fails.
+ *
+ * @param value - The cookie value to decode
  */
 function tryDecode(value: string) {
   try {
@@ -42,7 +52,19 @@ function tryDecode(value: string) {
 }
 
 /**
- * Registers custom decorators with the browser client
+ * Extends the browser client with AdonisJS-specific cookie functionality.
+ *
+ * This function registers decorators that add cookie management methods to the
+ * Playwright browser context. It enables setting and getting signed, encrypted,
+ * and plain cookies during browser tests.
+ *
+ * @param cookieClient - The AdonisJS cookie client for cookie operations
+ * @param baseURL - Optional base URL for determining cookie domain
+ *
+ * @example
+ * ```js
+ * extendBrowserClient(app.container.use('cookie'), 'http://localhost:3333')
+ * ```
  */
 export function extendBrowserClient(cookieClient: CookieClient, baseURL?: string) {
   debug('extending @japa/browser-client with adonisjs specific methods')

src/extend_context.ts

@@ -14,12 +14,31 @@ import type { Router } from '@adonisjs/core/http'
 import './types/extended.js'
 import debug from './debug.ts'
 
+/**
+ * Extends the Japa test context with AdonisJS-specific methods.
+ *
+ * This function adds route generation and REPL functionality to the test context.
+ * It provides access to AdonisJS router for URL generation and allows starting
+ * the AdonisJS REPL during tests for interactive debugging.
+ *
+ * @param router - The AdonisJS HTTP router instance
+ * @param repl - The AdonisJS REPL instance
+ *
+ * @example
+ * ```js
+ * extendContext(app.container.use('router'), app.container.use('repl'))
+ * ```
+ */
 export function extendContext(router: Router, repl: Repl) {
   debug('extending japa context with adonisjs specific methods')
 
   /**
-   * Starts the AdonisJS repl and resolves the promise when
-   * the repl is exited.
+   * Starts the AdonisJS REPL and resolves when the REPL is exited.
+   *
+   * This function creates a promise that resolves when the REPL session ends,
+   * allowing for interactive debugging during test execution.
+   *
+   * @param context - Optional context object to make available in the REPL
    */
   function startRepl(context?: Record<any, any>) {
     return new Promise<void>((resolve) => {