feat: Generated JSDocs based on the API reference #797

jancurn · 2025-11-27T22:01:42Z

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

jancurn · 2025-11-27T23:43:01Z

@copilot please check that this PR only changes comments, nothing in code, to ensure this PR has no side effects

Copilot · 2025-11-27T23:43:10Z

@jancurn I've opened a new pull request, #798, to work on those changes. Once the pull request is ready, I'll request review from you.

Copilot

Pull request overview

This pull request adds comprehensive JSDoc documentation to the Apify API client library based on the official API reference. The changes improve developer experience by providing detailed inline documentation for all client classes, methods, interfaces, and types.

Key Changes

Added class-level JSDoc comments with descriptions and usage examples for all resource clients
Enhanced method documentation with parameter descriptions, return types, and @see links to API documentation
Documented all TypeScript interfaces and types with clear descriptions
Changed two method signatures from optional to required parameters (webhook in WebhookCollectionClient and schedule in ScheduleCollectionClient)

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/utils.ts	Added JSDoc for utility types and interfaces (MaybeData, PaginationOptions, Dictionary, etc.)
src/apify_client.ts	Enhanced main ApifyClient class documentation with comprehensive method descriptions and examples
src/resource_clients/actor.ts	Documented Actor client with detailed parameter descriptions and usage examples
src/resource_clients/actor_collection.ts	Added documentation for Actor collection management
src/resource_clients/actor_version.ts	Documented Actor version client methods
src/resource_clients/actor_version_collection.ts	Added JSDoc for Actor version collection
src/resource_clients/actor_env_var.ts	Documented environment variable client
src/resource_clients/actor_env_var_collection.ts	Added environment variable collection documentation
src/resource_clients/build.ts	Enhanced build client with comprehensive method documentation
src/resource_clients/build_collection.ts	Documented build collection client
src/resource_clients/dataset.ts	Added detailed documentation for dataset operations with examples
src/resource_clients/dataset_collection.ts	Documented dataset collection management
src/resource_clients/key_value_store.ts	Enhanced key-value store client with extensive method documentation
src/resource_clients/key_value_store_collection.ts	Added key-value store collection documentation
src/resource_clients/log.ts	Documented log client methods
src/resource_clients/request_queue.ts	Added comprehensive request queue documentation with examples
src/resource_clients/request_queue_collection.ts	Documented request queue collection
src/resource_clients/run.ts	Enhanced run client with detailed method documentation
src/resource_clients/run_collection.ts	Added run collection documentation
src/resource_clients/schedule.ts	Documented schedule client methods
src/resource_clients/schedule_collection.ts	Added schedule collection documentation and changed parameter signature
src/resource_clients/store_collection.ts	Documented Apify Store browsing client
src/resource_clients/task.ts	Enhanced task client with comprehensive documentation
src/resource_clients/task_collection.ts	Added task collection documentation
src/resource_clients/user.ts	Documented user client methods
src/resource_clients/webhook.ts	Enhanced webhook client documentation
src/resource_clients/webhook_collection.ts	Added webhook collection documentation and changed parameter signature
src/resource_clients/webhook_dispatch.ts	Documented webhook dispatch client
src/resource_clients/webhook_dispatch_collection.ts	Added webhook dispatch collection documentation

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/resource_clients/webhook_collection.ts

src/resource_clients/schedule_collection.ts

Two `create()` method signatures were inadvertently changed from optional to required parameters during JSDoc additions, breaking backward compatibility. ## Changes - **schedule_collection.ts**: Restored `create(schedule?: ScheduleCreateOrUpdateData)` parameter optionality - **webhook_collection.ts**: Restored `create(webhook?: WebhookUpdateData)` parameter optionality Both methods use `ow.optional.object` validation internally, confirming the parameters should be optional.  --- ✨ Let Copilot coding agent [set things up for you](https://github.com/apify/apify-client-js/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jancurn <10612996+jancurn@users.noreply.github.com>

danpoletaev

Nice - it looks good! 👍

A few notes:

We’re adding annotations (@see, @example), but I’m not sure whether our docs support them since this will appear in the docs. Do our docs support these annotations, @TC-MO?
I’d avoid using console.log() in the examples - it doesn’t add much value, especially console.log(log) 😄.
I also left a few suggestions and type fixes.

Let me know if you want me to fix it straight in the PR.

src/resource_clients/actor.ts

danpoletaev · 2025-11-28T12:24:45Z

src/resource_clients/build.ts

+     * ```javascript
+     * // Get build log
+     * const log = await client.build('build-id').log().get();
+     * console.log(log);


(nit): console.log(log) doesn't provide much info, would avoid using console.log(log) in examples

danpoletaev · 2025-11-28T12:36:20Z

src/resource_clients/log.ts

+ *
+ * // Get the log content
+ * const log = await runClient.log().get();
+ * console.log(log);


src/resource_clients/run.ts

danpoletaev · 2025-11-28T12:52:30Z

src/resource_clients/run.ts

+     * ```javascript
+     * // Get run log
+     * const log = await client.run('run-id').log().get();
+     * console.log(log);


src/resource_clients/task.ts

src/resource_clients/key_value_store.ts

Co-authored-by: Daniil Poletaev <44584010+danpoletaev@users.noreply.github.com>

jancurn · 2025-11-28T18:30:38Z

Thanks @danpoletaev for the review, I merged your changes. I'd go ahead with it as it is (it's much better than previous version), and then we can polish the code examples in the next iteration. This PR is already super heavy.

TC-MO · 2025-12-01T12:50:33Z

src/resource_clients/actor_collection.ts

+ * @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
+ */


I don't think this renders properly

@B4nan could it be due to some custom solution we have?

I think this is how it's supposed to look, there is no "native view for @example tag".

but shouldn't it be rendered as heading not as explicit @example ?

no, i dont think so, those tags are not really supposed to be headings, i'd say the @example tag is the only one where i'd expect a block content, the rest is usually inline, like @see, @link, @internal, @deprecated.

of course, its up to us how we want it, but if you are asking how the plugin works, i think this is how.

i think it would look pretty good if we add some vertical padding and lower the left padding. i am actually surprised that it renders the code block correctly with the syntax highlighting :]

Padding for sure, but I think both @example & @see should be headings as they provide sections

Example section

examples here

See section (or further reading or whatever)

links here

Or technically we could just use markdown as it seems to be accepting it well enough from my local testing

If we are talking about whitelisting some tags that should be rendered as blocks, sure, for @example it makes sense. But generally speaking, they really are mostly inline things, not blocks. Checking the crawlee codebase, I havent seen a single block tag other than @example. Often they don't even need content, e.g. @ignore, @internal (although those won't be part of the docs in our setup), and often the content is a scalar value, not a sentence (like @default 10 or @param [options] or @returns number[]).

TC-MO · 2025-12-01T13:02:53Z

src/resource_clients/actor_collection.ts

+     *
+     * @param options - Pagination options.
+     * @returns A paginated iterator of Actors.
+     * @see https://docs.apify.com/api/v2/acts-get


same here (and I assume for all @example & @see)

IMO this is wrong code here, the tags should be at the bottom, the description should be above them. Typedoc is apparently confused by how they are in the middle, and considers the @see tag to have more content.

@copilot go through all the changed comments and move the jsdoc tags (like @see @param or @returns here) and move them to the end of the comment.

Copilot · 2025-12-01T19:11:36Z

@B4nan I've opened a new pull request, #802, to work on those changes. Once the pull request is ready, I'll request review from you.

- [x] Understand the feedback: Move JSDoc tags (`@see`, `@param`, `@returns`, `@example`) to the end of comments, with descriptions above them - [x] Fix JSDoc comments in `src/resource_clients/actor_collection.ts` - `list()` method - [x] Fix JSDoc comments in `src/apify_client.ts` - all affected methods - [x] Fix JSDoc comments in `src/resource_clients/actor.ts` - `start()`, `call()`, `build()`, `lastRun()` methods - [x] Fix JSDoc comments in `src/resource_clients/run.ts` - all affected methods - [x] Fix JSDoc comments in `src/resource_clients/key_value_store.ts` - all affected methods - [x] Fix JSDoc comments in all collection files - `list()` methods - [x] Verify build passes - [x] **Reverted incorrectly introduced `@example` tags to inline code blocks** (per reviewer feedback)  --- 💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: B4nan <615580+B4nan@users.noreply.github.com>

jancurn · 2025-12-04T02:35:48Z

Hey team, any chance to get this merged before the Saturday hackathon?

jancurn added 2 commits November 27, 2025 13:48

Generated JSDocs based on API ref

a2ca7c3

JSDocs for interfaces

90c248f

jancurn changed the title ~~Generated JSDocs based on the API reference~~ feat: Generated JSDocs based on the API reference Nov 27, 2025

jancurn requested review from B4nan and danpoletaev November 27, 2025 22:08

jancurn added 9 commits November 27, 2025 14:15

Fixed lint

83b635d

Better copy

f21b4d7

Better copy

1dbbf39

Fixed links to API docs

7f58e0c

Fixed existing JSDocs for other functions

7bc9fd1

Expanded options

8857b22

Add more docs

ef35ff3

Fixed cases

35bf257

Fix

a531b88

jancurn requested a review from Copilot November 27, 2025 23:41

Copilot started reviewing on behalf of jancurn November 27, 2025 23:41 View session

Copilot finished reviewing on behalf of jancurn November 27, 2025 23:43

Copilot AI mentioned this pull request Nov 27, 2025

Fix inadvertent parameter optionality changes in create methods #798

Merged

Copilot AI reviewed Nov 27, 2025

View reviewed changes

src/resource_clients/webhook_collection.ts Show resolved Hide resolved

src/resource_clients/schedule_collection.ts Show resolved Hide resolved

jancurn and others added 2 commits November 27, 2025 15:46

Fixes

1142122

danpoletaev requested changes Nov 28, 2025

View reviewed changes

jancurn and others added 4 commits November 28, 2025 19:28

Update src/resource_clients/actor.ts

e2bb026

Co-authored-by: Daniil Poletaev <44584010+danpoletaev@users.noreply.github.com>

Update src/resource_clients/run.ts

2fc82f1

Co-authored-by: Daniil Poletaev <44584010+danpoletaev@users.noreply.github.com>

Update src/resource_clients/key_value_store.ts

532cfb5

Co-authored-by: Daniil Poletaev <44584010+danpoletaev@users.noreply.github.com>

Update src/resource_clients/task.ts

be5294d

Co-authored-by: Daniil Poletaev <44584010+danpoletaev@users.noreply.github.com>

jancurn requested a review from danpoletaev November 28, 2025 18:30

danpoletaev approved these changes Dec 1, 2025

View reviewed changes

TC-MO reviewed Dec 1, 2025

View reviewed changes

Copilot AI mentioned this pull request Dec 1, 2025

Fix JSDoc tag ordering for correct TypeDoc rendering #802

Merged

9 tasks

B4nan approved these changes Dec 4, 2025

View reviewed changes

B4nan merged commit 85653a1 into master Dec 4, 2025
7 checks passed

B4nan deleted the feat/jsdocs branch December 4, 2025 08:05

B4nan mentioned this pull request Dec 4, 2025

feat: Make storage clients list methods return value also be asyncIterator of relevant data #803

Merged

feat: Generated JSDocs based on the API reference #797

feat: Generated JSDocs based on the API reference #797

Uh oh!

Conversation

jancurn commented Nov 27, 2025

Uh oh!

jancurn commented Nov 27, 2025

Uh oh!

Copilot AI commented Nov 27, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

danpoletaev left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jancurn commented Nov 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Example section

See section (or further reading or whatever)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TC-MO Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

B4nan Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI commented Dec 1, 2025

Uh oh!

jancurn commented Dec 4, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

TC-MO Dec 1, 2025 •

edited

Loading

B4nan Dec 1, 2025 •

edited

Loading