feat: Generated JSDocs based on the API reference (#797)

See https://apify.slack.com/archives/CQ96RHG2U/p1764257199836629

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: jancurn <[email protected]>
Co-authored-by: Daniil Poletaev <[email protected]>
Co-authored-by: B4nan <[email protected]>

Author: 4 people

src/apify_client.ts

@@ -6,6 +6,29 @@ import type { PaginatedIterator, PaginatedList, PaginationOptions } from '../uti
 import type { Actor, ActorDefaultRunOptions, ActorExampleRunInput, ActorStandby } from './actor';
 import type { ActorVersion } from './actor_version';
 
+/**
+ * Client for managing the collection of Actors in your account.
+ *
+ * Provides methods to list and create Actors. To access an individual Actor,
+ * use the `actor()` method on the main ApifyClient.
+ *
+ * @example
+ * ```javascript
+ * const client = new ApifyClient({ token: 'my-token' });
+ * const actorsClient = client.actors();
+ *
+ * // List all Actors
+ * const { items } = await actorsClient.list();
+ *
+ * // Create a new Actor
+ * const newActor = await actorsClient.create({
+ *   name: 'my-actor',
+ *   title: 'My Actor'
+ * });
+ * ```
+ *
+ * @see https://docs.apify.com/platform/actors
+ */
 export class ActorCollectionClient extends ResourceCollectionClient {
     /**
      * @hidden
@@ -18,20 +41,24 @@ export class ActorCollectionClient extends ResourceCollectionClient {
     }
 
     /**
-     * https://docs.apify.com/api/v2#/reference/actors/actor-collection/get-list-of-actors
+     * Lists all Actors.
      *
      * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched
      * items in a single API call is limited.
      * ```javascript
      * const paginatedList = await client.list(options);
-     *```
+     * ```
      *
      * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are
      * retrieved.
      *
      * ```javascript
      * for await (const singleItem of client.list(options)) {...}
      * ```
+     *
+     * @param options - Pagination options.
+     * @returns A paginated iterator of Actors.
+     * @see https://docs.apify.com/api/v2/acts-get
      */
     list(options: ActorCollectionListOptions = {}): PaginatedIterator<ActorCollectionListItem> {
         ow(
@@ -49,7 +76,11 @@ export class ActorCollectionClient extends ResourceCollectionClient {
     }
 
     /**
-     * https://docs.apify.com/api/v2#/reference/actors/actor-collection/create-actor
+     * Creates a new Actor.
+     *
+     * @param actor - The Actor data.
+     * @returns The created Actor object.
+     * @see https://docs.apify.com/api/v2/acts-post
      */
     async create(actor: ActorCollectionCreateOptions): Promise<Actor> {
         ow(actor, ow.optional.object);

src/resource_clients/actor.ts

@@ -4,6 +4,28 @@ import type { ApiClientSubResourceOptions } from '../base/api_client';
 import { ResourceClient } from '../base/resource_client';
 import type { ActorEnvironmentVariable } from './actor_version';
 
+/**
+ * Client for managing a specific Actor environment variable.
+ *
+ * Environment variables are key-value pairs that are available to the Actor during execution.
+ * This client provides methods to get, update, and delete environment variables.
+ *
+ * @example
+ * ```javascript
+ * const client = new ApifyClient({ token: 'my-token' });
+ * const actorClient = client.actor('my-actor-id');
+ * const versionClient = actorClient.version('0.1');
+ *
+ * // Get an environment variable
+ * const envVarClient = versionClient.envVar('MY_VAR');
+ * const envVar = await envVarClient.get();
+ *
+ * // Update environment variable
+ * await envVarClient.update({ value: 'new-value' });
+ * ```
+ *
+ * @see https://docs.apify.com/platform/actors/development/actor-definition/environment-variables
+ */
 export class ActorEnvVarClient extends ResourceClient {
     /**
      * @hidden
@@ -16,22 +38,31 @@ export class ActorEnvVarClient extends ResourceClient {
     }
 
     /**
-     * https://docs.apify.com/api/v2#/reference/actors/environment-variable-object/get-environment-variable
+     * Retrieves the environment variable.
+     *
+     * @returns The environment variable object, or `undefined` if it does not exist.
+     * @see https://docs.apify.com/api/v2/act-version-env-var-get
      */
     async get(): Promise<ActorEnvironmentVariable | undefined> {
         return this._get();
     }
 
     /**
-     * https://docs.apify.com/api/v2#/reference/actors/environment-variable-object/update-environment-variable
+     * Updates the environment variable.
+     *
+     * @param actorEnvVar - The updated environment variable data.
+     * @returns The updated environment variable object.
+     * @see https://docs.apify.com/api/v2/act-version-env-var-put
      */
     async update(actorEnvVar: ActorEnvironmentVariable): Promise<ActorEnvironmentVariable> {
         ow(actorEnvVar, ow.object);
         return this._update(actorEnvVar);
     }
 
     /**
-     * https://docs.apify.com/api/v2#/reference/actors/environment-variable-object/delete-environment-variable
+     * Deletes the environment variable.
+     *
+     * @see https://docs.apify.com/api/v2/act-version-env-var-delete
      */
     async delete(): Promise<void> {
         return this._delete();

src/resource_clients/actor_collection.ts

@@ -5,6 +5,32 @@ import { ResourceCollectionClient } from '../base/resource_collection_client';
 import type { PaginatedList, PaginationOptions } from '../utils';
 import type { ActorEnvironmentVariable } from './actor_version';
 
+/**
+ * Client for managing the collection of environment variables for an Actor version.
+ *
+ * Environment variables are key-value pairs that are available to the Actor during execution.
+ * This client provides methods to list and create environment variables.
+ *
+ * @example
+ * ```javascript
+ * const client = new ApifyClient({ token: 'my-token' });
+ * const actorClient = client.actor('my-actor-id');
+ * const versionClient = actorClient.version('0.1');
+ *
+ * // List all environment variables
+ * const envVarsClient = versionClient.envVars();
+ * const { items } = await envVarsClient.list();
+ *
+ * // Create a new environment variable
+ * const newEnvVar = await envVarsClient.create({
+ *   name: 'MY_VAR',
+ *   value: 'my-value',
+ *   isSecret: false
+ * });
+ * ```
+ *
+ * @see https://docs.apify.com/platform/actors/development/actor-definition/environment-variables
+ */
 export class ActorEnvVarCollectionClient extends ResourceCollectionClient {
     /**
      * @hidden
@@ -17,20 +43,24 @@ export class ActorEnvVarCollectionClient extends ResourceCollectionClient {
     }
 
     /**
-     * https://docs.apify.com/api/v2#/reference/actors/environment-variable-collection/get-list-of-environment-variables
+     * Lists all environment variables of this Actor version.
      *
      * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched
      * items in a single API call is limited.
      * ```javascript
      * const paginatedList = await client.list(options);
-     *```
+     * ```
      *
      * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are
      * retrieved.
      *
      * ```javascript
      * for await (const singleItem of client.list(options)) {...}
      * ```
+     *
+     * @param options - Pagination options.
+     * @returns A paginated iterator of environment variables.
+     * @see https://docs.apify.com/api/v2/act-version-env-vars-get
      */
     list(
         options: ActorEnvVarCollectionListOptions = {},
@@ -47,7 +77,11 @@ export class ActorEnvVarCollectionClient extends ResourceCollectionClient {
     }
 
     /**
-     * https://docs.apify.com/api/v2#/reference/actors/environment-variable-collection/create-environment-variable
+     * Creates a new environment variable for this Actor version.
+     *
+     * @param actorEnvVar - The environment variable data.
+     * @returns The created environment variable object.
+     * @see https://docs.apify.com/api/v2/act-version-env-vars-post
      */
     async create(actorEnvVar: ActorEnvironmentVariable): Promise<ActorEnvironmentVariable> {
         ow(actorEnvVar, ow.optional.object);

src/resource_clients/actor_env_var.ts

@@ -5,6 +5,27 @@ import { ResourceClient } from '../base/resource_client';
 import { ActorEnvVarClient } from './actor_env_var';
 import { ActorEnvVarCollectionClient } from './actor_env_var_collection';
 
+/**
+ * Client for managing a specific Actor version.
+ *
+ * Actor versions represent specific builds or snapshots of an Actor's code. This client provides
+ * methods to get, update, and delete versions, as well as manage their environment variables.
+ *
+ * @example
+ * ```javascript
+ * const client = new ApifyClient({ token: 'my-token' });
+ * const actorClient = client.actor('my-actor-id');
+ *
+ * // Get a specific version
+ * const versionClient = actorClient.version('0.1');
+ * const version = await versionClient.get();
+ *
+ * // Update version
+ * await versionClient.update({ buildTag: 'latest' });
+ * ```
+ *
+ * @see https://docs.apify.com/platform/actors/development/actor-definition/versions
+ */
 export class ActorVersionClient extends ResourceClient {
     /**
      * @hidden
@@ -17,14 +38,21 @@ export class ActorVersionClient extends ResourceClient {
     }
 
     /**
-     * https://docs.apify.com/api/v2#/reference/actors/version-object/get-version
+     * Retrieves the Actor version.
+     *
+     * @returns The Actor version object, or `undefined` if it does not exist.
+     * @see https://docs.apify.com/api/v2/act-version-get
      */
     async get(): Promise<FinalActorVersion | undefined> {
         return this._get();
     }
 
     /**
-     * https://docs.apify.com/api/v2#/reference/actors/version-object/update-version
+     * Updates the Actor version with the specified fields.
+     *
+     * @param newFields - Fields to update.
+     * @returns The updated Actor version object.
+     * @see https://docs.apify.com/api/v2/act-version-put
      */
     async update(newFields: ActorVersion): Promise<FinalActorVersion> {
         ow(newFields, ow.object);
@@ -33,14 +61,20 @@ export class ActorVersionClient extends ResourceClient {
     }
 
     /**
-     * https://docs.apify.com/api/v2#/reference/actors/version-object/delete-version
+     * Deletes the Actor version.
+     *
+     * @see https://docs.apify.com/api/v2/act-version-delete
      */
     async delete(): Promise<void> {
         return this._delete();
     }
 
     /**
-     * TODO: https://docs.apify.com/api/v2#/reference/actors/env-var-object
+     * Returns a client for the specified environment variable of this Actor version.
+     *
+     * @param envVarName - Name of the environment variable.
+     * @returns A client for the environment variable.
+     * @see https://docs.apify.com/api/v2/act-version-env-var-get
      */
     envVar(envVarName: string): ActorEnvVarClient {
         ow(envVarName, ow.string);
@@ -52,8 +86,10 @@ export class ActorVersionClient extends ResourceClient {
     }
 
     /**
-     * TODO: https://docs.apify.com/api/v2#/reference/actors/env-var-collection
-     * @return {ActorVersionCollectionClient}
+     * Returns a client for the environment variables of this Actor version.
+     *
+     * @returns A client for the Actor version's environment variables.
+     * @see https://docs.apify.com/api/v2/act-version-env-vars-get
      */
     envVars(): ActorEnvVarCollectionClient {
         return new ActorEnvVarCollectionClient(this._subResourceOptions());

src/resource_clients/actor_env_var_collection.ts

@@ -5,6 +5,30 @@ import { ResourceCollectionClient } from '../base/resource_collection_client';
 import type { PaginatedList, PaginationOptions } from '../utils';
 import type { ActorVersion, FinalActorVersion } from './actor_version';
 
+/**
+ * Client for managing the collection of Actor versions.
+ *
+ * Actor versions represent specific builds or snapshots of an Actor's code. This client provides
+ * methods to list and create versions for a specific Actor.
+ *
+ * @example
+ * ```javascript
+ * const client = new ApifyClient({ token: 'my-token' });
+ * const actorClient = client.actor('my-actor-id');
+ *
+ * // List all versions
+ * const versionsClient = actorClient.versions();
+ * const { items } = await versionsClient.list();
+ *
+ * // Create a new version
+ * const newVersion = await versionsClient.create({
+ *   versionNumber: '0.2',
+ *   buildTag: 'latest'
+ * });
+ * ```
+ *
+ * @see https://docs.apify.com/platform/actors/development/actor-definition/versions
+ */
 export class ActorVersionCollectionClient extends ResourceCollectionClient {
     /**
      * @hidden
@@ -17,20 +41,24 @@ export class ActorVersionCollectionClient extends ResourceCollectionClient {
     }
 
     /**
-     * https://docs.apify.com/api/v2#/reference/actors/version-collection/get-list-of-versions
+     * Lists all Actor versions.
      *
      * Awaiting the return value (as you would with a Promise) will result in a single API call. The amount of fetched
      * items in a single API call is limited.
      * ```javascript
      * const paginatedList = await client.list(options);
-     *```
+     * ```
      *
      * Asynchronous iteration is also supported. This will fetch additional pages if needed until all items are
      * retrieved.
      *
      * ```javascript
      * for await (const singleItem of client.list(options)) {...}
      * ```
+     *
+     * @param options - Pagination options.
+     * @returns A paginated iterator of Actor versions.
+     * @see https://docs.apify.com/api/v2/act-versions-get
      */
     list(
         options: ActorVersionCollectionListOptions = {},
@@ -48,7 +76,11 @@ export class ActorVersionCollectionClient extends ResourceCollectionClient {
     }
 
     /**
-     * https://docs.apify.com/api/v2#/reference/actors/version-collection/create-version
+     * Creates a new Actor version.
+     *
+     * @param actorVersion - The Actor version data.
+     * @returns The created Actor version object.
+     * @see https://docs.apify.com/api/v2/act-versions-post
      */
     async create(actorVersion: ActorVersion): Promise<FinalActorVersion> {
         ow(actorVersion, ow.optional.object);