docs: write docs for alias API

Author: bevzzz

src/alias/index.ts

@@ -3,10 +3,52 @@ import { WeaviateAlias, WeaviateAliasResponse } from '../openapi/types.js';
 import { Alias, CreateAliasInput, UpdateAliasInput } from './types.js';
 
 export interface Aliases {
+  /**
+   * Create alias for a collection.
+   *
+   * The collection must exist prior to aliasing it.
+   * One alias cannot be created for multiple collections simultaneously.
+   *
+   * @param {string} [opt.collection] Original collection name.
+   * @param {string} [opt.alias] Alias for collection.
+   * @returns {Promise<void>} Awaitable promise.
+   * */
   create: (opt: CreateAliasInput) => Promise<void>;
+
+  /**
+   * List all aliases defined in the schema.
+   *
+   * @param {string | undefined} collection Get all aliases defined for this collection.
+   * @returns {Promise<Alias[] | undefined>} An array of aliases.
+   */
   listAll: (collection?: string) => Promise<Alias[] | undefined>;
+
+  /**
+   * Get information about an alias.
+   *
+   * @param {string} alias Alias to fetch.
+   * @return {Promise<Alias>} Alias definition.
+   */
   get: (alias: string) => Promise<Alias>;
+
+  /**
+   * Replace target collection the alias points to.
+   *
+   * To change the alias that points to the collection,
+   * delete the alias and create a new one.
+   *
+   * @param {string} [opt.alias] Alias to update.
+   * @param {string} [opt.collection] New collection the alias should point to.
+   * @return {Promise<void>} Awaitable promise.
+   */
   update: (opt: UpdateAliasInput) => Promise<void>;
+
+  /**
+   * Delete a collection alias.
+   *
+   * @param {string} alias Alias definition to delete.
+   * @return {Promise<void>} Awaitable promise.
+   */
   delete: (alias: string) => Promise<void>;
 }
 

src/roles/index.ts

@@ -154,10 +154,8 @@ export const permissions = {
   /**
    * Create a set of permissions specific to Weaviate's collection aliasing functionality.
    *
-   * For all collections, provide the `collection` argument as `'*'`.
-   *
-   * @param {string | string[]} [args.alias] Aliases to create permissions for.
-   * @returns {BackupsPermission[]} The permissions for the specified collections.
+   * @param {string | string[]} [args.alias] Aliases that will be associated with these permissions.
+   * @returns {AliasPermission[]} The permissions for the specified aliases.
    */
   aliases: (args: {
     alias: string | string[];