docs: add more information to JSDoc comments

packages/core/src/actor.ts

@@ -21,7 +21,12 @@ import { Paginator } from './paginate'
 import { Preferences } from './preference'
 
 export class BaseActor {
-  constructor(readonly instance: AppBskyNS, readonly actor: string) {}
+  /**
+   * Creates a new instance of the Actor class.
+   * @param instance The instance of the `AppBskyNS` class.
+   * @param actor The atproto identifier of the actor.
+   */
+  constructor(readonly instance: AppBskyNS, readonly actor: AtIdentifier) {}
 
   /**
    * Get a list of starter packs created by the actor.

packages/core/src/feed.ts

@@ -11,6 +11,10 @@ import type {
 import { Paginator } from './paginate'
 
 export class Feed {
+  /**
+   * Creates a new instance of the Feed class.
+   * @param instance The instance of the `AppBskyNS` class.
+   */
   constructor(private instance: AppBskyNS) {}
 
   /**

packages/core/src/global.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A atproto identifier.
+ * @example 'at://did:plc:z72i7hdynmk6r22z27h6tvur'
+ */
+type AtIdentifier = string

packages/core/src/index.ts

@@ -9,23 +9,38 @@ import type {
 import { Paginator } from './paginate'
 
 export class TSky {
+  /**
+   * Creates a new instance of the TSky class.
+   * @param instance The instance of the `AppBskyNS` class.
+   */
   constructor(private instance: AppBskyNS) {}
 
   /**
    * Get detailed profile view of an actor. Does not require auth, but contains relevant metadata with auth.
+   * @param identifier The atproto identifier of the actor.
+   * @param options Additional options.
+   * @returns The detailed profile view of the actor.
    */
   profile(
     identifier: string,
     options?: AppBskyActorGetProfile.CallOptions
   ): Promise<AppBskyActorDefs.ProfileViewDetailed>
   /**
    * Get detailed profile views of multiple actors.
+   * @param identifiers The atproto identifiers of the actors.
+   * @param options Additional options.
    */
   profile(
     identifiers: string[],
     options?: AppBskyActorGetProfiles.CallOptions
   ): Promise<AppBskyActorDefs.ProfileViewDetailed[]>
 
+  /**
+   * Get detailed profile view of an actor. Does not require auth, but contains relevant metadata with auth.
+   * @param identifier The atproto identifier or identifiers of the actor/s.
+   * @param options Additional options.
+   * @returns The detailed profile view of the actor/s.
+   */
   async profile(
     identifier: string | string[],
     options?:
@@ -51,6 +66,9 @@ export class TSky {
 
   /**
    * Find actor suggestions for a prefix search term. Expected use is for auto-completion during text field entry. Does not require auth.
+   * @param params The query parameters.
+   * @param options Additional options.
+   * @returns The actor suggestions.
    */
   async typeahead(
     params: AppBskyActorSearchActorsTypeahead.QueryParams,
@@ -66,6 +84,9 @@ export class TSky {
 
   /**
    * Find actors (profiles) matching search criteria. Does not require auth.
+   * @param params The query parameters.
+   * @param options Additional options.
+   * @returns The paginator for the search results.
    */
   async search(
     params: AppBskyActorSearchActors.QueryParams = {},

packages/core/src/list.ts

@@ -6,10 +6,18 @@ import type {
 import { Paginator } from './paginate'
 
 export class BskyList {
+  /**
+   * Creates a new instance of the List class.
+   * @param instance The instance of the `AppBskyNS` class.
+   * @param uri The atproto identifier of the list.
+   */
   constructor(private instance: AppBskyNS, private uri: string) {}
 
   /**
    * Gets a 'view' (with additional context) of a specified list.
+   * @param limit The maximum number of items to return per page.
+   * @param options Additional options.
+   * @returns The list view paginator.
    */
   about(limit?: number, options?: AppBskyGraphGetList.CallOptions) {
     return new Paginator(async (cursor) => {
@@ -28,6 +36,9 @@ export class BskyList {
 
   /**
    * Get a feed of recent posts from a list (posts and reposts from any actors on the list). Does not require auth.
+   * @param limit The maximum number of items to return per page.
+   * @param options Additional options.
+   * @returns The list feed paginator.
    */
   feed(limit?: number, options?: AppBskyFeedGetListFeed.CallOptions) {
     return new Paginator(async (cursor) => {

packages/core/src/paginate.ts

@@ -3,9 +3,18 @@ interface CursorResponse {
   [key: string]: unknown
 }
 
+/**
+ * A paginator for fetching data from a cursor-based API.
+ * @template T The type of the cursor response.
+ */
 export class Paginator<T extends CursorResponse> {
   readonly values: T[] = []
 
+  /**
+   * Creates a new instance of the Paginator class.
+   * @param onNext The function to call to get the next page of data.
+   * @param defaultValues The default values to start with.
+   */
   constructor(
     private onNext: (cursor?: string) => Promise<T>,
     defaultValues?: T[],
@@ -18,10 +27,18 @@ export class Paginator<T extends CursorResponse> {
     // this.next();
   }
 
+  /**
+   * Clone this paginator.
+   * @returns A new paginator with the same values.
+   */
   clone() {
     return new Paginator(this.onNext, this.values)
   }
 
+  /**
+   * Get the data for the next page.
+   * @returns The data for the next page. If there is no more data, returns `null`.
+   */
   async next() {
     const hasValues = this.values.length > 0
 

packages/core/src/post.ts

@@ -10,10 +10,17 @@ import type {
 import { Paginator } from './paginate'
 
 export class Post {
+  /**
+   * Creates a new instance of the Post class.
+   * @param instance The instance of the `AppBskyNS` class.
+   */
   constructor(private instance: AppBskyNS) {}
 
   /**
    * Get posts in a thread. Does not require auth, but additional metadata and filtering will be applied for authed requests.
+   * @param params The query parameters.
+   * @param options Additional options.
+   * @returns The posts in the thread.
    */
   async threads(
     params: AppBskyFeedGetPostThread.QueryParams,
@@ -26,6 +33,9 @@ export class Post {
 
   /**
    * Get like records which reference a subject (by AT-URI and CID).
+   * @param params The query parameters.
+   * @param options Additional options.
+   * @returns The likes paginator of a post.
    */
   likes(
     params: AppBskyFeedGetLikes.QueryParams,
@@ -43,6 +53,9 @@ export class Post {
 
   /**
    * Get a list of quotes for a given post.
+   * @param params The query parameters.
+   * @param options Additional options.
+   * @returns The quotes paginator of a post.
    */
   quotes(
     params: AppBskyFeedGetQuotes.QueryParams,
@@ -60,6 +73,9 @@ export class Post {
 
   /**
    * Get a list of reposts for a given post.
+   * @param params The query parameters.
+   * @param options Additional options.
+   * @returns The reposts paginator of a post.
    */
   repostedBy(
     params: AppBskyFeedGetRepostedBy.QueryParams,
@@ -77,6 +93,10 @@ export class Post {
 
   /**
    * Find posts matching search criteria, returning views of those posts.
+   * @param instance The instance of the `AppBskyNS` class.
+   * @param params The query parameters.
+   * @param options Additional options.
+   * @returns The posts paginator.
    */
   static search(
     instance: AppBskyNS,
@@ -95,6 +115,10 @@ export class Post {
 
   /**
    * Gets post views for a specified list of posts (by AT-URI). This is sometimes referred to as 'hydrating' a 'feed skeleton'.
+   * @param instance The instance of the `AppBskyNS` class.
+   * @param posts The list of posts to get.
+   * @param options Additional options.
+   * @returns The hydrated posts.
    */
   static async getMany(
     instance: AppBskyNS,

packages/core/src/preference.ts

@@ -5,10 +5,16 @@ import type {
 } from '@atproto/api'
 
 export class Preferences {
+  /**
+   * Creates a new instance of the Preferences class.
+   * @param instance The instance of the `AppBskyNS` class.
+   */
   constructor(private instance: AppBskyNS) {}
 
   /**
    * Get private preferences attached to the current account. Expected use is synchronization between multiple devices, and import/export during account migration. Requires auth.
+   * @param options Additional options.
+   * @returns The private preferences attached to the account.
    */
   async get(options?: AppBskyActorGetPreferences.CallOptions) {
     const res = await this.instance.actor.getPreferences(undefined, options)
@@ -18,6 +24,9 @@ export class Preferences {
 
   /**
    * Set the private preferences attached to the account.
+   * @param preferences The preferences to set.
+   * @param options Additional options.
+   * @returns An empty promise
    */
   async set(
     preferences: AppBskyActorPutPreferences.InputSchema['preferences'],

packages/core/src/starterPack.ts

@@ -11,6 +11,8 @@ export class StarterPack {
 
   /**
    * Gets a view of a starter pack.
+   * @param options Additional options.
+   * @returns The starter pack view.
    */
   async about(options?: AppBskyGraphGetStarterPack.CallOptions) {
     const res = await this.instance.graph.getStarterPack(
@@ -25,6 +27,11 @@ export class StarterPack {
 
   /**
    * Search for starter packs.
+   * @param instance The instance of the `AppBskyNS` class.
+   * @param query The search query.
+   * @param limit The maximum number of items to return per page.
+   * @param options Additional options.
+   * @returns The starter pack search paginator.
    */
   static search(
     instance: AppBskyNS,
@@ -48,6 +55,10 @@ export class StarterPack {
 
   /**
    * Get views for a list of starter packs.
+   * @param instance The instance of the `AppBskyNS` class.
+   * @param starterpacks The atproto identifiers of the starter packs.
+   * @param options Additional options.
+   * @returns The starter pack views.
    */
   static async getMany(
     instance: AppBskyNS,

packages/core/src/video.ts

@@ -7,11 +7,22 @@ import type {
   BlobRef,
 } from '@atproto/api'
 
+export type VideoJobState =
+  | 'JOB_STATE_COMPLETED'
+  | 'JOB_STATE_FAILED'
+  | (string & {})
+
 export class Video {
+  /**
+   * Creates a new instance of the Video class.
+   * @param instance The instance of the `AppBskyNS` class.
+   */
   constructor(private instance: AppBskyNS) {}
 
   /**
    * Get video upload limits for the authenticated user.
+   * @param options Additional options.
+   * @returns The video upload limits.
    */
   async limit(options?: AppBskyVideoGetUploadLimits.CallOptions) {
     const res = await this.instance.video.getUploadLimits({}, options)
@@ -21,6 +32,9 @@ export class Video {
 
   /**
    * Get status details for a video processing job.
+   * @param jobId The job ID.
+   * @param options Additional options.
+   * @returns The status details for the video processing job.
    */
   async status(jobId: string, options?: AppBskyVideoGetJobStatus.CallOptions) {
     const res = await this.instance.video.getJobStatus({ jobId }, options)
@@ -30,6 +44,9 @@ export class Video {
 
   /**
    * Upload a video to be processed then stored on the PDS.
+   * @param data The video upload data.
+   * @param options Additional options.
+   * @returns The status of the video processing job.
    */
   async upload(
     data: AppBskyVideoUploadVideo.InputSchema,
@@ -45,7 +62,7 @@ class JobStatus {
   jobId: string
   did: string
   /** The state of the video processing job. All values not listed as a known value indicate that the job is in process. */
-  state: 'JOB_STATE_COMPLETED' | 'JOB_STATE_FAILED' | (string & {})
+  state: VideoJobState
   /** Progress within the current processing state. */
   progress?: number
   blob?: BlobRef
@@ -66,6 +83,7 @@ class JobStatus {
 
   /**
    * Update status details for a video processing job.
+   * @param options Additional options.
    */
   async refresh(options?: AppBskyVideoGetJobStatus.CallOptions) {
     const res = await this.instance.video.getJobStatus(