Misc documentation fixes, mostly around optional fields and return types (#2194)

* update createRole

* misc docs fixes, mostly optional

* parity: return undefined for 204 no content response

* undo return undefined

* undo createRole changes
https://github.com/discordeno/discordeno/pull/2195#pullrequestreview-971240431

* undo reordering

Co-authored-by: ITOH <to@itoh.at>

helpers/channels/deleteStageInstance.ts

@@ -2,5 +2,5 @@ import type { Bot } from "../../bot.ts";
 
 /** Deletes the Stage instance. Requires the user to be a moderator of the Stage channel. */
 export async function deleteStageInstance(bot: Bot, channelId: bigint) {
-  await bot.rest.runMethod<undefined>(bot.rest, "delete", bot.constants.endpoints.STAGE_INSTANCE(channelId));
+  await bot.rest.runMethod(bot.rest, "delete", bot.constants.endpoints.STAGE_INSTANCE(channelId));
 }

helpers/guilds/scheduledEvents/createScheduledEvent.ts

@@ -49,7 +49,7 @@ export async function createScheduledEvent(bot: Bot, guildId: bigint, options: C
 export interface CreateScheduledEvent {
   /** the channel id of the scheduled event. */
   channelId?: bigint;
-  /** location of the event */
+  /** location of the event. Required for events with `entityType: ScheduledEventEntityType.External` */
   location?: string;
   /** the name of the scheduled event */
   name: string;
@@ -57,7 +57,7 @@ export interface CreateScheduledEvent {
   description: string;
   /** the time the scheduled event will start */
   scheduledStartTime: number;
-  /** the time the scheduled event will end if it does end. */
+  /** the time the scheduled event will end if it does end. Required for events with `entityType: ScheduledEventEntityType.External` */
   scheduledEndTime?: number;
   /** the privacy level of the scheduled event */
   privacyLevel?: ScheduledEventPrivacyLevel;

helpers/guilds/scheduledEvents/editScheduledEvent.ts

@@ -47,11 +47,11 @@ export interface EditScheduledEvent {
   /** the channel id of the scheduled event. null if switching to external event. */
   channelId: bigint | null;
   /** location of the event */
-  location: string;
+  location?: string;
   /** the name of the scheduled event */
   name: string;
   /** the description of the scheduled event */
-  description: string;
+  description?: string;
   /** the time the scheduled event will start */
   scheduledStartTime: number;
   /** the time the scheduled event will end if it does end. */

helpers/roles/createRole.ts

@@ -10,6 +10,8 @@ export async function createRole(bot: Bot, guildId: bigint, options: CreateGuild
     hoist: options.hoist,
     mentionable: options.mentionable,
     permissions: bot.utils.calculateBits(options?.permissions || []),
+    icon: options.icon,
+    unicode_emoji: options.unicodeEmoji,
     reason,
   });
 
@@ -32,4 +34,6 @@ export interface CreateGuildRole {
   mentionable?: boolean;
   /** The role's unicode emoji (if the guild has the `ROLE_ICONS` feature) */
   unicodeEmoji?: string;
+  /** the role's icon image (if the guild has the `ROLE_ICONS` feature) */
+  icon?: string;
 }

types/discord.ts

@@ -1553,7 +1553,7 @@ export interface DiscordScheduledEvent {
   /** the number of users subscribed to the scheduled event */
   user_count?: number;
   /** the cover image hash of the scheduled event */
-  image: string | null;
+  image?: string | null;
 }
 
 export interface DiscordScheduledEventEntityMetadata {