From ae650a04d92c6921effde896d128f3116cc055d5 Mon Sep 17 00:00:00 2001 From: Fleny Date: Tue, 2 Sep 2025 08:17:59 +0200 Subject: [PATCH] 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 --- packages/bot/src/desiredProperties.ts | 58 ++++++++++++++----- .../bot/src/transformers/toggles/guild.ts | 7 ++- .../bot/src/transformers/toggles/member.ts | 3 +- packages/bot/src/transformers/types.ts | 10 ++-- packages/bot/typedoc.jsonc | 5 -- packages/gateway/src/Shard.ts | 4 +- packages/gateway/typedoc.jsonc | 3 - packages/rest/src/types.ts | 10 +++- packages/rest/typedoc.jsonc | 3 - packages/types/typedoc.jsonc | 3 - packages/utils/typedoc.jsonc | 3 - typedoc.jsonc | 4 ++ 12 files changed, 67 insertions(+), 46 deletions(-) delete mode 100644 packages/bot/typedoc.jsonc delete mode 100644 packages/gateway/typedoc.jsonc delete mode 100644 packages/rest/typedoc.jsonc delete mode 100644 packages/types/typedoc.jsonc delete mode 100644 packages/utils/typedoc.jsonc diff --git a/packages/bot/src/desiredProperties.ts b/packages/bot/src/desiredProperties.ts index 2502f1c29..d3a888447 100644 --- 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 } -type KeyByValue = { +/** @private This is subject to breaking changes without notices */ +export type KeyByValue = { [Key in keyof TObj]: TObj[Key] extends TValue ? Key : never }[keyof TObj] -type Complete = { +/** @private This is subject to breaking changes without notices */ +export type Complete = { [K in keyof TObj]-?: undefined extends TObj[K] ? TDefault : Exclude } -type JoinTuple = 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 readonly [infer F extends string, ...infer R extends string[]] ? R['length'] extends 0 ? F : `${F}${TDelimiter}${JoinTuple}` : '' -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, > = Exclude< @@ -888,21 +897,25 @@ type DesirableProperties< : NonNullable[number]) > -/** @internal This is subject to breaking changes without notices */ +/** @private This is subject to breaking changes without notices */ export type DesiredPropertiesMapper = { [Key in DesirableProperties]: boolean } declare const TypeErrorSymbol: unique symbol -interface DesiredPropertiesError { + +/** @private This is subject to breaking changes without notices */ +export interface DesiredPropertiesError { [TypeErrorSymbol]: T } -type AreDependenciesSatisfied | undefined, TProps> = { +/** @private This is subject to breaking changes without notices */ +export type AreDependenciesSatisfied | undefined, TProps> = { [K in keyof T]: IsKeyDesired extends true ? true : false } -type IsKeyDesired | undefined, TProps> = TKey extends keyof TProps // The key has a desired props? +/** @private This is subject to breaking changes without notices */ +export type IsKeyDesired | 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 = IsKeyDesired< +/** @private This is subject to breaking changes without notices */ +export type RemoveKeyIfUndesired = IsKeyDesired< Key, TransformersDesiredPropertiesMetadata[KeyByValue]['dependencies'], TProps[KeyByValue] @@ -936,7 +950,8 @@ type RemoveKeyIfUndesired ? 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 : TIsDesired -type IsObject = T extends object ? (T extends Function ? false : true) : false +/** @private This is subject to breaking changes without notices */ +export type IsObject = 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 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 extends Array // is it an array? ? // Yes, apply the desired props TransformProperty[] @@ -991,6 +1011,9 @@ export type TransformProperty } +/** + * The desired properties for each transformer object. + */ export type TransformersDesiredProperties = { [Key in keyof TransformersObjects]: DesiredPropertiesMapper } -/** @internal This is subject to breaking changes without notices */ +/** @private This is subject to breaking changes without notices */ export type CompleteDesiredProperties, TTDefault extends boolean = false> = { [K in keyof TransformersDesiredProperties]: Complete & T[K], TTDefault> } diff --git a/packages/bot/src/transformers/toggles/guild.ts b/packages/bot/src/transformers/toggles/guild.ts index a87a61e5e..37285097a 100644 --- 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] diff --git a/packages/bot/src/transformers/toggles/member.ts b/packages/bot/src/transformers/toggles/member.ts index 26a037734..0e4efabbb 100644 --- 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 */ diff --git a/packages/bot/src/transformers/types.ts b/packages/bot/src/transformers/types.ts index 7b35b0c06..a5d76df51 100644 --- 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 { diff --git a/packages/bot/typedoc.jsonc b/packages/bot/typedoc.jsonc deleted file mode 100644 index 37dd476d0..000000000 --- a/packages/bot/typedoc.jsonc +++ /dev/null @@ -1,5 +0,0 @@ -{ - "entryPoints": ["./src/index.ts"], - // Exclude other packages' dist folders to avoid duplicated types in the documentation - "exclude": ["../*/dist/**/*"] -} diff --git a/packages/gateway/src/Shard.ts b/packages/gateway/src/Shard.ts index 6d6ff6523..d74cb27d5 100644 --- 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 diff --git a/packages/gateway/typedoc.jsonc b/packages/gateway/typedoc.jsonc deleted file mode 100644 index be8ce11f3..000000000 --- a/packages/gateway/typedoc.jsonc +++ /dev/null @@ -1,3 +0,0 @@ -{ - "entryPoints": ["./src/index.ts"] -} diff --git a/packages/rest/src/types.ts b/packages/rest/src/types.ts index 5e456e1cd..8e76d1322 100644 --- 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. diff --git a/packages/rest/typedoc.jsonc b/packages/rest/typedoc.jsonc deleted file mode 100644 index be8ce11f3..000000000 --- a/packages/rest/typedoc.jsonc +++ /dev/null @@ -1,3 +0,0 @@ -{ - "entryPoints": ["./src/index.ts"] -} diff --git a/packages/types/typedoc.jsonc b/packages/types/typedoc.jsonc deleted file mode 100644 index be8ce11f3..000000000 --- a/packages/types/typedoc.jsonc +++ /dev/null @@ -1,3 +0,0 @@ -{ - "entryPoints": ["./src/index.ts"] -} diff --git a/packages/utils/typedoc.jsonc b/packages/utils/typedoc.jsonc deleted file mode 100644 index be8ce11f3..000000000 --- a/packages/utils/typedoc.jsonc +++ /dev/null @@ -1,3 +0,0 @@ -{ - "entryPoints": ["./src/index.ts"] -} diff --git a/typedoc.jsonc b/typedoc.jsonc index e0c1a506f..67971f72f 100644 --- 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,