refactor(typedoc): update typedoc configuration and mark internal APIs as private (#4405)

The typedoc config is now only in the top-level config file instead of also being one per package and all internal APIs are now marked as private so typedoc won't generate documentation for them, however we still need to export them to avoid typedoc warnings The new internal APIs that are exported, since are marked as `@private` can have breaking changes without notices
2026-05-21 02:40:08 +00:00 · 2025-09-02 08:17:59 +02:00
parent 2a7cd9b2a5
commit ae650a04d9
12 changed files with 67 additions and 46 deletions
--- a/packages/bot/src/desiredProperties.ts
+++ b/packages/bot/src/desiredProperties.ts
@@ -61,7 +61,7 @@ import type {
 /**
 * All the objects that support desired properties
 *
- * @internal This is subject to breaking changes at any time
+ * @private This is subject to breaking changes at any time
 */
 export interface TransformersObjects {
  activityInstance: ActivityInstance
@@ -122,8 +122,12 @@ export interface TransformersObjects {
 // NOTE: the top-level objects need both the dependencies and alwaysPresents even if empty when the key is specified, this is due the extends & nullability on DesiredPropertiesMetadata
 //       internal properties needs to be in the alwaysPresents array, depending on an always present value is accepted

-/** Metadata for typescript to create the correct types for desired properties */
-interface TransformersDesiredPropertiesMetadata extends DesiredPropertiesMetadata {
+/**
+ * Metadata for typescript to create the correct types for desired properties
+ *
+ * @private This is subject to breaking changes without notices
+ */
+export interface TransformersDesiredPropertiesMetadata extends DesiredPropertiesMetadata {
  channel: {
    dependencies: {
      archived: ['toggles']
@@ -852,21 +856,25 @@ export function createDesiredPropertiesObject<T extends RecursivePartial<Transfo
  } satisfies TransformersDesiredProperties as CompleteDesiredProperties<T, TDefault>
 }

-type KeyByValue<TObj, TValue> = {
+/** @private This is subject to breaking changes without notices */
+export type KeyByValue<TObj, TValue> = {
  [Key in keyof TObj]: TObj[Key] extends TValue ? Key : never
 }[keyof TObj]

-type Complete<TObj, TDefault> = {
+/** @private This is subject to breaking changes without notices */
+export type Complete<TObj, TDefault> = {
  [K in keyof TObj]-?: undefined extends TObj[K] ? TDefault : Exclude<TObj[K], undefined>
 }

-type JoinTuple<T extends string[], TDelimiter extends string> = T extends readonly [infer F extends string, ...infer R extends string[]]
+/** @private This is subject to breaking changes without notices */
+export type JoinTuple<T extends string[], TDelimiter extends string> = T extends readonly [infer F extends string, ...infer R extends string[]]
  ? R['length'] extends 0
    ? F
    : `${F}${TDelimiter}${JoinTuple<R, TDelimiter>}`
  : ''

-type DesiredPropertiesMetadata = {
+/** @private This is subject to breaking changes without notices */
+export type DesiredPropertiesMetadata = {
  [K in keyof TransformersObjects]: {
    dependencies?: {
      [Key in keyof TransformersObjects[K]]?: (keyof TransformersObjects[K])[]
@@ -875,7 +883,8 @@ type DesiredPropertiesMetadata = {
  }
 }

-type DesirableProperties<
+/** @private This is subject to breaking changes without notices */
+export type DesirableProperties<
  T extends TransformersObjects[keyof TransformersObjects],
  TKey extends keyof TransformersObjects = KeyByValue<TransformersObjects, T>,
 > = Exclude<
@@ -888,21 +897,25 @@ type DesirableProperties<
      : NonNullable<TransformersDesiredPropertiesMetadata[TKey]['alwaysPresents']>[number])
 >

-/** @internal This is subject to breaking changes without notices */
+/** @private This is subject to breaking changes without notices */
 export type DesiredPropertiesMapper<T extends TransformersObjects[keyof TransformersObjects]> = {
  [Key in DesirableProperties<T>]: boolean
 }

 declare const TypeErrorSymbol: unique symbol
-interface DesiredPropertiesError<T extends string> {
+
+/** @private This is subject to breaking changes without notices */
+export interface DesiredPropertiesError<T extends string> {
  [TypeErrorSymbol]: T
 }

-type AreDependenciesSatisfied<T, TDependencies extends Record<string, string[]> | undefined, TProps> = {
+/** @private This is subject to breaking changes without notices */
+export type AreDependenciesSatisfied<T, TDependencies extends Record<string, string[]> | undefined, TProps> = {
  [K in keyof T]: IsKeyDesired<T[K], TDependencies, TProps> extends true ? true : false
 }

-type IsKeyDesired<TKey, TDependencies extends Record<string, string[]> | undefined, TProps> = TKey extends keyof TProps // The key has a desired props?
+/** @private This is subject to breaking changes without notices */
+export type IsKeyDesired<TKey, TDependencies extends Record<string, string[]> | undefined, TProps> = TKey extends keyof TProps // The key has a desired props?
  ? // Yes, is it true?
    TProps[TKey] extends true
    ? // Yes, this is a key to include
@@ -928,7 +941,8 @@ export enum DesiredPropertiesBehavior {
  ChangeType,
 }

-type RemoveKeyIfUndesired<Key, T, TProps extends TransformersDesiredProperties> = IsKeyDesired<
+/** @private This is subject to breaking changes without notices */
+export type RemoveKeyIfUndesired<Key, T, TProps extends TransformersDesiredProperties> = IsKeyDesired<
  Key,
  TransformersDesiredPropertiesMetadata[KeyByValue<TransformersObjects, T>]['dependencies'],
  TProps[KeyByValue<TransformersObjects, T>]
@@ -936,7 +950,8 @@ type RemoveKeyIfUndesired<Key, T, TProps extends TransformersDesiredProperties>
  ? Key
  : never

-type GetErrorWhenUndesired<
+/** @private This is subject to breaking changes without notices */
+export type GetErrorWhenUndesired<
  Key extends keyof T,
  T,
  TProps extends TransformersDesiredProperties,
@@ -949,7 +964,8 @@ type GetErrorWhenUndesired<
  >,
 > = TIsDesired extends true ? TransformProperty<T[Key], TProps, TBehavior> : TIsDesired

-type IsObject<T> = T extends object ? (T extends Function ? false : true) : false
+/** @private This is subject to breaking changes without notices */
+export type IsObject<T> = T extends object ? (T extends Function ? false : true) : false

 // If the object is a transformed object, a collection of transformed object or an array of transformed objects we need to apply the desired props to them as well
 // NOTE: changing the order of these ternaries can cause bugs, for this reason we check in this order:
@@ -961,6 +977,10 @@ type IsObject<T> = T extends object ? (T extends Function ? false : true) : fals
 //      - Is it an interaction resolved data channel?
 //      - Is it an object?
 //      - It's not an object
+
+/**
+ * Transform a generic object properties based on the desired properties and behavior for other transformer objects in the object.
+ */
 export type TransformProperty<T, TProps extends TransformersDesiredProperties, TBehavior extends DesiredPropertiesBehavior> = T extends Array<infer U> // is it an array?
  ? // Yes, apply the desired props
    TransformProperty<U, TProps, TBehavior>[]
@@ -991,6 +1011,9 @@ export type TransformProperty<T, TProps extends TransformersDesiredProperties, T
              : // No, this is a normal value such as string / bigint / number
                T

+/**
+ * Apply desired properties to a transformer object.
+ */
 export type SetupDesiredProps<
  T extends TransformersObjects[keyof TransformersObjects],
  TProps extends TransformersDesiredProperties,
@@ -1005,11 +1028,14 @@ export type SetupDesiredProps<
    : TransformProperty<T[Key], TProps, TBehavior>
 }

+/**
+ * The desired properties for each transformer object.
+ */
 export type TransformersDesiredProperties = {
  [Key in keyof TransformersObjects]: DesiredPropertiesMapper<TransformersObjects[Key]>
 }

-/** @internal This is subject to breaking changes without notices */
+/** @private This is subject to breaking changes without notices */
 export type CompleteDesiredProperties<T extends RecursivePartial<TransformersDesiredProperties>, TTDefault extends boolean = false> = {
  [K in keyof TransformersDesiredProperties]: Complete<Partial<TransformersDesiredProperties[K]> & T[K], TTDefault>
 }
--- a/packages/bot/src/transformers/toggles/guild.ts
+++ b/packages/bot/src/transformers/toggles/guild.ts
@@ -1,7 +1,8 @@
 import { type DiscordGuild, GuildFeatures } from '@discordeno/types'
 import { ToggleBitfieldBigint } from './ToggleBitfield.js'

-const featureNames = [
+/** @private This is subject to breaking changes without notices */
+export const guildFeatureNames = [
  'animatedBanner',
  'animatedIcon',
  'applicationCommandPermissionsV2',
@@ -169,7 +170,7 @@ export class GuildToggles extends ToggleBitfieldBigint {
  get features(): GuildFeatureKeys[] {
    const features: GuildFeatureKeys[] = []
    for (const key of Object.keys(GuildToggle)) {
-      if (!featureNames.includes(key as GuildFeatureKeys)) continue
+      if (!guildFeatureNames.includes(key as GuildFeatureKeys)) continue
      if (!super.contains(GuildToggle[key as GuildToggleKeys])) continue

      features.push(key as GuildFeatureKeys)
@@ -383,4 +384,4 @@ export class GuildToggles extends ToggleBitfieldBigint {

 export type GuildToggleKeys = keyof typeof GuildToggle

-export type GuildFeatureKeys = (typeof featureNames)[number]
+export type GuildFeatureKeys = (typeof guildFeatureNames)[number]
--- a/packages/bot/src/transformers/toggles/member.ts
+++ b/packages/bot/src/transformers/toggles/member.ts
@@ -1,7 +1,8 @@
 import { type DiscordMember, MemberFlags } from '@discordeno/types'
 import { ToggleBitfield } from './ToggleBitfield.js'

-const memberFlags = ['didRejoin', 'startedOnboarding', 'bypassesVerification', 'completedOnboarding'] as const
+/** @private This is subject to breaking changes without notices */
+export const memberFlags = ['didRejoin', 'startedOnboarding', 'bypassesVerification', 'completedOnboarding'] as const

 export const MemberToggle = {
  /** Whether the user is deafened in voice channels */
--- a/packages/bot/src/transformers/types.ts
+++ b/packages/bot/src/transformers/types.ts
@@ -411,7 +411,7 @@ export interface Channel {
  /**
   * Thread-specific fields not needed by other channels.
   *
-   * @internal
+   * @private
   * This field is an internal field, subject to breaking changes.
   */
  internalThreadMetadata?: InternalChannelThreadMetadata
@@ -425,7 +425,7 @@ export interface Channel {
  /**
   * Explicit permission overwrites for members and roles
   *
-   * @internal
+   * @private
   * Use channel.permissionOverwrites. This is for internal use only, and prone to breaking changes.
   */
  internalOverwrites?: bigint[]
@@ -480,7 +480,7 @@ export interface ForumTag {
 }

 /**
- * @internal
+ * @private
 * This is for internal purposes only, and subject to breaking changes
 */
 export interface InternalChannelThreadMetadata {
@@ -1502,7 +1502,7 @@ export interface Role {
  /**
   * Role tags
   *
-   * @internal
+   * @private
   * Use role.tags. This is for internal use only, and prone to breaking changes.
   */
  internalTags?: InternalRoleTags
@@ -1532,7 +1532,7 @@ export interface Role {
 }

 /**
- * @internal
+ * @private
 * This is for internal purposes only, and subject to breaking changes
 */
 export interface InternalRoleTags {
--- a/packages/bot/typedoc.jsonc
+++ b/packages/bot/typedoc.jsonc
@@ -1,5 +0,0 @@
-{
-  "entryPoints": ["./src/index.ts"],
-  // Exclude other packages' dist folders to avoid duplicated types in the documentation
-  "exclude": ["../*/dist/**/*"]
-}
--- a/packages/gateway/src/Shard.ts
+++ b/packages/gateway/src/Shard.ts
@@ -61,7 +61,7 @@ export class DiscordenoShard {
   * @remarks
   * This will be true if the close method has been called with either 1000 or 1001
   *
-   * @internal
+   * @private
   * This is for internal purposes only, and subject to breaking changes.
   */
  goingOffline = false
@@ -78,7 +78,7 @@ export class DiscordenoShard {
  /**
   * A function that will be called once the socket is closed and handleClose() has finished updating internal states.
   *
-   * @internal
+   * @private
   * This is for internal purposes only, and subject to breaking changes.
   */
  resolveAfterClose?: (close: CloseEvent) => void
--- a/packages/gateway/typedoc.jsonc
+++ b/packages/gateway/typedoc.jsonc
@@ -1,3 +0,0 @@
-{
-  "entryPoints": ["./src/index.ts"]
-}
--- a/packages/rest/src/types.ts
+++ b/packages/rest/src/types.ts
@@ -6,6 +6,7 @@ import type {
  BeginGuildPrune,
  BigString,
  Camelize,
+  ChannelTypes,
  CreateApplicationCommand,
  CreateApplicationEmoji,
  CreateAutoModerationRuleOptions,
@@ -34,6 +35,7 @@ import type {
  DiscordApplication,
  DiscordApplicationCommand,
  DiscordApplicationCommandPermissions,
+  DiscordApplicationIntegrationType,
  DiscordApplicationRoleConnection,
  DiscordApplicationRoleConnectionMetadata,
  DiscordAuditLog,
@@ -57,6 +59,7 @@ import type {
  DiscordGuildWidgetSettings,
  DiscordIncidentsData,
  DiscordIntegration,
+  DiscordInteraction,
  DiscordInteractionCallbackResponse,
  DiscordInvite,
  DiscordInviteMetadata,
@@ -117,6 +120,7 @@ import type {
  GetThreadMember,
  GetUserGuilds,
  GetWebhookMessageOptions,
+  GuildFeatures,
  InteractionCallbackData,
  InteractionCallbackOptions,
  InteractionResponse,
@@ -138,6 +142,8 @@ import type {
  ModifyLobby,
  ModifyRolePositions,
  ModifyWebhook,
+  ScheduledEventEntityType,
+  ScheduledEventStatus,
  SearchMembers,
  SendSoundboardSound,
  StartThreadWithMessage,
@@ -2079,7 +2085,7 @@ export interface RestManager {
   *
   * @param channelId - The ID of the channel to get the archived threads for.
   * @param options - The parameters for the fetching of threads.
-   * @returns An instance of {@link DiscordArchivedThreads}.
+   * @returns An instance of {@link DiscordListArchivedThreads}.
   *
   * @remarks
   * Requires the `READ_MESSAGE_HISTORY` permission.
@@ -2109,7 +2115,7 @@ export interface RestManager {
   *
   * @param channelId - The ID of the channel to get the archived threads for.
   * @param options - The parameters for the fetching of threads.
-   * @returns An instance of {@link DiscordArchivedThreads}.
+   * @returns An instance of {@link DiscordListArchivedThreads}.
   *
   * @remarks
   * Requires the `READ_MESSAGE_HISTORY` permission.
--- a/packages/rest/typedoc.jsonc
+++ b/packages/rest/typedoc.jsonc
@@ -1,3 +0,0 @@
-{
-  "entryPoints": ["./src/index.ts"]
-}
--- a/packages/types/typedoc.jsonc
+++ b/packages/types/typedoc.jsonc
@@ -1,3 +0,0 @@
-{
-  "entryPoints": ["./src/index.ts"]
-}
--- a/packages/utils/typedoc.jsonc
+++ b/packages/utils/typedoc.jsonc
@@ -1,3 +0,0 @@
-{
-  "entryPoints": ["./src/index.ts"]
-}
--- a/typedoc.jsonc
+++ b/typedoc.jsonc
@@ -2,6 +2,10 @@
  "$schema": "https://typedoc.org/schema.json",
  "entryPointStrategy": "packages",
  "entryPoints": ["packages/bot", "packages/gateway", "packages/rest", "packages/types", "packages/utils"],
+  "packageOptions": {
+    "entryPoints": ["./src/index.ts"],
+    "exclude": ["**/dist/**/*"]
+  },
  "out": "./website/api_reference/generated",
  "readme": "./website/api_reference/generated/_media/README.md",
  "cleanOutputDir": false,