From b3c242bd86c9bbf0a3cb285741070349bb848380 Mon Sep 17 00:00:00 2001 From: Szymon Uglis Date: Fri, 1 Nov 2024 23:02:09 +0100 Subject: [PATCH] docs: More docs and typos (#724) * Add some doc on builders * fix doc on reactions + add docs on guild builder * Fix Makefile; Fix template --------- Co-authored-by: Rapougnac --- Makefile | 4 +- .../builders/channel/channel_position.dart | 4 + lib/src/builders/channel/forum_tag.dart | 4 + lib/src/builders/channel/group_dm.dart | 2 + lib/src/builders/channel/guild_channel.dart | 99 +++++++++++++++++++ lib/src/builders/channel/stage_instance.dart | 11 +++ lib/src/builders/channel/thread.dart | 26 +++++ lib/src/builders/guild/auto_moderation.dart | 29 ++++++ lib/src/builders/guild/guild.dart | 50 ++++++++++ lib/src/models/channel/text_channel.dart | 2 +- lib/src/models/message/message.dart | 4 +- 11 files changed, 230 insertions(+), 5 deletions(-) diff --git a/Makefile b/Makefile index bdc3fb124..1aa3fdcb0 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ help: @fgrep -h "##" $(MAKEFILE_LIST) | sed -e 's/\(\:.*\#\#\)/\:\ /' | fgrep -v fgrep | sed -e 's/\\$$//' | sed -e 's/##//' format: ## Run dart format - dart format -l120 . + dart format -l 160 . fix: ## Run dart fix dart fix --apply @@ -23,4 +23,4 @@ fix-project: analyze fix format ## Fix whole project test-project: unit-tests integration-tests ## Run all tests -check-project: fix-project test-project ## Run all checks \ No newline at end of file +check-project: fix-project test-project ## Run all checks diff --git a/lib/src/builders/channel/channel_position.dart b/lib/src/builders/channel/channel_position.dart index e41a1d7b1..926107477 100644 --- a/lib/src/builders/channel/channel_position.dart +++ b/lib/src/builders/channel/channel_position.dart @@ -3,12 +3,16 @@ import 'package:nyxx/src/models/channel/guild_channel.dart'; import 'package:nyxx/src/models/snowflake.dart'; class ChannelPositionBuilder extends UpdateBuilder { + /// The channel id to update. Snowflake channelId; + /// The sorting position of the channel. int? position; + /// Whether to sync the permission overwrites with the new parent if moving to a new category. bool? lockPermissions; + /// The new parent ID for the channel that is moved. Snowflake? parentId; ChannelPositionBuilder({ diff --git a/lib/src/builders/channel/forum_tag.dart b/lib/src/builders/channel/forum_tag.dart index a702e4ade..678fc3b9c 100644 --- a/lib/src/builders/channel/forum_tag.dart +++ b/lib/src/builders/channel/forum_tag.dart @@ -4,12 +4,16 @@ import 'package:nyxx/src/models/snowflake.dart'; import 'package:nyxx/src/utils/building_helpers.dart'; class ForumTagBuilder extends CreateBuilder { + /// The name of the tag. (0-20 characters) String name; + /// Whether this tag can only be added to or removed from threads by a member with the [Permissions.manageThreads] permission. bool? isModerated; + /// The id of a guild's custom emoji. Snowflake? emojiId; + /// The unicode character of the emoji. String? emojiName; ForumTagBuilder({required this.name, this.isModerated, this.emojiId, this.emojiName}); diff --git a/lib/src/builders/channel/group_dm.dart b/lib/src/builders/channel/group_dm.dart index d60ee009b..fe0365ae5 100644 --- a/lib/src/builders/channel/group_dm.dart +++ b/lib/src/builders/channel/group_dm.dart @@ -4,8 +4,10 @@ import 'package:nyxx/src/builders/builder.dart'; import 'package:nyxx/src/models/channel/types/group_dm.dart'; class GroupDmUpdateBuilder extends UpdateBuilder { + /// The name of the group DM, if changed. String? name; + /// The icon, if changed. List? icon; GroupDmUpdateBuilder({this.name, this.icon}); diff --git a/lib/src/builders/channel/guild_channel.dart b/lib/src/builders/channel/guild_channel.dart index 442f4fd6c..4ea19232a 100644 --- a/lib/src/builders/channel/guild_channel.dart +++ b/lib/src/builders/channel/guild_channel.dart @@ -15,12 +15,24 @@ import 'package:nyxx/src/utils/building_helpers.dart'; import 'package:nyxx/src/utils/flags.dart'; class GuildChannelBuilder extends CreateBuilder { + /// {@template channel_name} + /// The name of the channel (1-100 characters) + /// {@endtemplate} String name; + /// {@template channel_type} + /// The type of the channel. + /// {@endtemplate} ChannelType type; + /// {@template channel_position} + /// The sorting position of the channel. + /// {@endtemplate} int? position; + /// {@template channel_permission_overwrites} + /// The explicit permission overwrites for members and roles. + /// {@endtemplate} List>? permissionOverwrites; GuildChannelBuilder({ @@ -40,10 +52,13 @@ class GuildChannelBuilder extends CreateBuilder { } class GuildChannelUpdateBuilder extends UpdateBuilder { + /// {@macro channel_name} String? name; + /// {@macro channel_position} int? position; + /// {@macro channel_permission_overwrites} List>? permissionOverwrites; GuildChannelUpdateBuilder({this.name, this.position = sentinelInteger, this.permissionOverwrites}); @@ -57,14 +72,30 @@ class GuildChannelUpdateBuilder extends UpdateBuilder } class GuildTextChannelBuilder extends GuildChannelBuilder { + /// {@template channel_topic} + /// The channel topic (0-4096 characters for [ChannelType.guildForum] and [ChannelType.guildMedia] channels, 0-1024 characters for all others) + /// {@endtemplate} String? topic; + /// {@template channel_rate_limit_per_user} + /// The duration after which the user will be able to send another message (0-21600 seconds). Members with the [Permissions.manageMessages] + /// or [Permissions.manageChannel] permission are unaffected. + /// {@endtemplate} Duration? rateLimitPerUser; + /// {@template channel_parent_id} + /// The parent channel's id for a [ChannelType.guildText] channel. + /// {@endtemplate} Snowflake? parentId; + /// {@template channel_nsfw} + /// Whether the channel is nsfw. + /// {@endtemplate} bool? isNsfw; + /// {@template channel_default_auto_archive_duration} + /// Default duration, copied onto newly created threads, in minutes, threads will stop showing in the channel list after the specified period of inactivity. + /// {@endtemplate} Duration? defaultAutoArchiveDuration; GuildTextChannelBuilder({ @@ -90,18 +121,26 @@ class GuildTextChannelBuilder extends GuildChannelBuilder { } class GuildTextChannelUpdateBuilder extends GuildChannelUpdateBuilder { + /// {@macro channel_type} ChannelType? type; + /// {@macro channel_topic} String? topic; + /// {@macro channel_nsfw} bool? isNsfw; + /// {@macro channel_rate_limit_per_user} Duration? rateLimitPerUser; + /// {@macro channel_parent_id} Snowflake? parentId; + /// {@macro channel_default_auto_archive_duration} Duration? defaultAutoArchiveDuration; + /// The initial rate_limit_per_user to set on newly created threads in a channel. + /// This field is copied to the thread at creation time and does not live update. Duration? defaultThreadRateLimitPerUser; GuildTextChannelUpdateBuilder({ @@ -131,12 +170,16 @@ class GuildTextChannelUpdateBuilder extends GuildChannelUpdateBuilder { + /// {@macro channel_topic} String? topic; + /// {@macro channel_parent_id} Snowflake? parentId; + /// {@macro channel_nsfw} bool? isNsfw; + /// {@macro channel_default_auto_archive_duration} Duration? defaultAutoArchiveDuration; GuildAnnouncementChannelBuilder({ @@ -160,14 +203,19 @@ class GuildAnnouncementChannelBuilder extends GuildChannelBuilder { + /// {@macro channel_type} ChannelType? type; + /// {@macro channel_topic} String? topic; + /// {@macro channel_nsfw} bool? isNsfw; + /// {@macro channel_parent_id} Snowflake? parentId; + /// {@macro channel_default_auto_archive_duration} Duration? defaultAutoArchiveDuration; GuildAnnouncementChannelUpdateBuilder({ @@ -193,20 +241,35 @@ class GuildAnnouncementChannelUpdateBuilder extends GuildChannelUpdateBuilder { + /// {@macro channel_topic} String? topic; + /// {@macro channel_rate_limit_per_user} Duration? rateLimitPerUser; + /// {@macro channel_parent_id} Snowflake? parentId; + /// {@macro channel_nsfw} bool? isNsfw; + /// {@macro channel_default_auto_archive_duration} Duration? defaultAutoArchiveDuration; + /// {@template default_reaction} + /// The emoji to show in the add reaction button on a thread in a [ChannelType.guildForum] or a [ChannelType.guildMedia] channel. + /// {@endtemplate} DefaultReaction? defaultReaction; + /// {@template tags} + /// The set of tags that can be used in a [ChannelType.guildForum] or a [ChannelType.guildMedia] channel. + /// {@endtemplate} List>? tags; + /// {@template default_sort_order} + /// The default sort order type used to order posts in [ChannelType.guildForum] and [ChannelType.guildMedia] channels. + /// Defaults to null, which indicates a preferred sort order hasn't been set by a channel admin. + /// {@endtemplate} ForumSort? defaultSortOrder; ForumChannelBuilder({ @@ -239,26 +302,40 @@ class ForumChannelBuilder extends GuildChannelBuilder { } class ForumChannelUpdateBuilder extends GuildChannelUpdateBuilder { + /// {@macro channel_type} String? topic; + /// {@macro channel_nsfw} bool? isNsfw; + /// {@macro channel_rate_limit_per_user} Duration? rateLimitPerUser; + /// {@macro channel_parent_id} Snowflake? parentId; + /// {@macro channel_default_auto_archive_duration} Duration? defaultAutoArchiveDuration; + /// {@template channel_flags} + /// Channel flags combined. + /// {@endtemplate} Flags? flags; + /// {@macro tags} List>? tags; + /// {@macro default_reaction} DefaultReaction? defaultReaction; + /// {@macro default_thread_rate_limit_per_user} Duration? defaultThreadRateLimitPerUser; + /// {@macro default_sort_order} ForumSort? defaultSortOrder; + /// The default forum layout view used to display posts in [ChannelType.guildForum] channels. Defaults to [ForumLayout.notSet], + /// which indicates a layout view has not been set by a channel admin. ForumLayout? defaultLayout; ForumChannelUpdateBuilder({ @@ -297,16 +374,32 @@ class ForumChannelUpdateBuilder extends GuildChannelUpdateBuilder } abstract class _GuildVoiceOrStageChannelBuilder extends GuildChannelBuilder { + /// {@template channel_bitrate} + /// The bitrate (in bits) of the voice or stage channel; min 8000. + /// {@endtemplate} int? bitRate; + /// {@template channel_user_limit} + /// The user limit of the voice or stage channel; min 0, max 99 for voice channels, max 10,000 for stage channels. + /// {@endtemplate} int? userLimit; + /// {@template voice_channel_parent_id} + /// The parent channel's id for a [ChannelType.guildVoice] or a [ChannelType.guildStageVoice] channel. + /// {@endtemplate} Snowflake? parentId; + /// {@macro channel_nsfw} bool? isNsfw; + /// {@template rtc_region} + /// Channel voice region id, automatic when set to null. + /// {@endtemplate} String? rtcRegion; + /// {@template video_quality_mode} + /// The camera video quality mode of the voice channel. + /// {@endtemplate} VideoQualityMode? videoQualityMode; _GuildVoiceOrStageChannelBuilder({ @@ -363,16 +456,22 @@ class GuildStageChannelBuilder extends _GuildVoiceOrStageChannelBuilder extends GuildChannelUpdateBuilder { + /// {@macro channel_nsfw} bool? isNsfw; + /// {@macro channel_bitrate} int? bitRate; + /// {@macro channel_user_limit} int? userLimit; + /// {@macro voice_channel_parent_id} Snowflake? parentId; + /// {@macro rtc_region} String? rtcRegion; + /// {@macro video_quality_mode} VideoQualityMode? videoQualityMode; _GuildVoiceOrStageChannelUpdateBuilder({ diff --git a/lib/src/builders/channel/stage_instance.dart b/lib/src/builders/channel/stage_instance.dart index f398f0ca7..3ee5d0123 100644 --- a/lib/src/builders/channel/stage_instance.dart +++ b/lib/src/builders/channel/stage_instance.dart @@ -2,13 +2,22 @@ import 'package:nyxx/src/builders/builder.dart'; import 'package:nyxx/src/models/channel/stage_instance.dart'; import 'package:nyxx/src/models/snowflake.dart'; +/// A Stage Instance holds information about a live stage. class StageInstanceBuilder extends CreateBuilder { + /// {@template stage_instance_topic} + /// The topic of the Stage instance (1-120 characters). + /// {@endtemplate} String topic; + /// {@template stage_instance_privacy_level} + /// The privacy level of the Stage instance. + /// {@endtemplate} PrivacyLevel? privacyLevel; + /// Notify @everyone that a Stage instance has started. bool? sendStartNotification; + /// The guild scheduled event associated with this Stage instance. Snowflake? guildScheduledEventId; StageInstanceBuilder({ @@ -28,8 +37,10 @@ class StageInstanceBuilder extends CreateBuilder { } class StageInstanceUpdateBuilder extends UpdateBuilder { + /// {@macro stage_instance_topic} String? topic; + /// {@macro stage_instance_privacy_level} PrivacyLevel? privacyLevel; StageInstanceUpdateBuilder({this.topic, this.privacyLevel}); diff --git a/lib/src/builders/channel/thread.dart b/lib/src/builders/channel/thread.dart index f838d1f10..6439cb7b5 100644 --- a/lib/src/builders/channel/thread.dart +++ b/lib/src/builders/channel/thread.dart @@ -7,10 +7,15 @@ import 'package:nyxx/src/models/snowflake.dart'; import 'package:nyxx/src/utils/flags.dart'; class ThreadFromMessageBuilder extends CreateBuilder { + /// {@template thread_name} + /// The name of the thread. + /// {@endtemplate} String name; + /// {@macro channel_default_auto_archive_duration} Duration? autoArchiveDuration; + /// {@macro channel_rate_limit_per_user} Duration? rateLimitPerUser; ThreadFromMessageBuilder({required this.name, this.autoArchiveDuration, this.rateLimitPerUser}); @@ -29,14 +34,20 @@ class ThreadBuilder extends CreateBuilder { static const archiveThreeDays = Duration(minutes: 4320); static const archiveOneWeek = Duration(minutes: 10080); + /// {@macro thread_name} String name; + /// {@macro channel_default_auto_archive_duration} Duration? autoArchiveDuration; + /// {@macro channel_type} ChannelType type; + /// Whether non-moderators can add other non-moderators to a thread; only available on private threads. + // TODO: Prefix with is*? bool? invitable; + /// {@macro channel_rate_limit_per_user} Duration? rateLimitPerUser; ThreadBuilder({required this.name, this.autoArchiveDuration, required this.type, this.invitable, this.rateLimitPerUser}); @@ -56,14 +67,21 @@ class ThreadBuilder extends CreateBuilder { } class ForumThreadBuilder extends CreateBuilder { + /// {@macro thread_name} String name; + /// {@macro channel_default_auto_archive_duration} Duration? autoArchiveDuration; + /// {@macro channel_rate_limit_per_user} Duration? rateLimitPerUser; + /// Contents of the first message in the forum thread. MessageBuilder message; + /// {@template thread_applied_tags} + /// The IDs of the set of tags that have been applied to a thread in a [ChannelType.guildForum] channel. + /// {@endtemplate} List? appliedTags; ForumThreadBuilder({required this.name, this.autoArchiveDuration, this.rateLimitPerUser, required this.message, this.appliedTags}); @@ -79,20 +97,28 @@ class ForumThreadBuilder extends CreateBuilder { } class ThreadUpdateBuilder extends UpdateBuilder { + /// {@macro thread_name} String? name; + /// Whether the thread is archived. bool? isArchived; + /// {@macro channel_default_auto_archive_duration} Duration? autoArchiveDuration; + /// Whether the thread is locked; only available on private threads. bool? isLocked; + /// Whether non-moderators can add other non-moderators to a thread; only available on private threads. bool? isInvitable; + /// {@macro channel_rate_limit_per_user} Duration? rateLimitPerUser; + /// {@macro channel_flags} Flags? flags; + /// {@macro thread_applied_tags} List? appliedTags; ThreadUpdateBuilder({ diff --git a/lib/src/builders/guild/auto_moderation.dart b/lib/src/builders/guild/auto_moderation.dart index 6a7458eba..2b823bbf7 100644 --- a/lib/src/builders/guild/auto_moderation.dart +++ b/lib/src/builders/guild/auto_moderation.dart @@ -3,20 +3,42 @@ import 'package:nyxx/src/models/guild/auto_moderation.dart'; import 'package:nyxx/src/models/snowflake.dart'; class AutoModerationRuleBuilder extends CreateBuilder { + /// {@template auto_moderation_rule_name} + /// The rule name. + /// {@endtemplate} String name; + /// {@template auto_moderation_rule_event_type} + /// The event type that will trigger this rule. + /// {@endtemplate} AutoModerationEventType eventType; + /// The trigger type that will trigger this rule. TriggerType triggerType; + /// {@template auto_moderation_rule_trigger_metadata} + /// The trigger metadata. + /// {@endtemplate} TriggerMetadataBuilder? metadata; + /// {@template auto_moderation_rule_actions} + /// The actions that will be executed when this rule is triggered. + /// {@endtemplate} List actions; + /// {@template auto_moderation_rule_is_enabled} + /// Whether this rule is enabled. + /// {@endtemplate} bool? isEnabled; + /// {@template auto_moderation_rule_exempt_role_ids} + /// The role ids that are exempt from this rule. + /// {@endtemplate} List? exemptRoleIds; + /// {@template auto_moderation_rule_exempt_channel_ids} + /// The channel ids that are exempt from this rule. + /// {@endtemplate} List? exemptChannelIds; AutoModerationRuleBuilder({ @@ -118,18 +140,25 @@ class AutoModerationRuleBuilder extends CreateBuilder { } class AutoModerationRuleUpdateBuilder extends UpdateBuilder { + /// {@macro auto_moderation_rule_name} String? name; + /// {@macro auto_moderation_rule_event_type} AutoModerationEventType? eventType; + /// {@macro auto_moderation_rule_trigger_metadata} TriggerMetadataBuilder? metadata; + /// {@macro auto_moderation_rule_actions} List? actions; + /// {@macro auto_moderation_rule_is_enabled} bool? isEnabled; + /// {@macro auto_moderation_rule_exempt_role_ids} List? exemptRoleIds; + /// {@macro auto_moderation_rule_exempt_channel_ids} List? exemptChannelIds; AutoModerationRuleUpdateBuilder({ diff --git a/lib/src/builders/guild/guild.dart b/lib/src/builders/guild/guild.dart index 2722e2be0..1d45e3470 100644 --- a/lib/src/builders/guild/guild.dart +++ b/lib/src/builders/guild/guild.dart @@ -10,26 +10,57 @@ import 'package:nyxx/src/models/snowflake.dart'; import 'package:nyxx/src/utils/flags.dart'; class GuildBuilder extends CreateBuilder { + /// {@template guild_name} + /// The name of the guild. (2-100 characters) + /// {@endtemplate} String name; + /// {@template guild_icon} + /// The icon of the guild. + /// {@endtemplate} ImageBuilder? icon; + /// {@template guild_verification_level} + /// The verification level of the guild. + /// {@endtemplate} VerificationLevel? verificationLevel; + /// {@template guild_default_message_notification_level} + /// The default message notification level of the guild. + /// {@endtemplate} MessageNotificationLevel? defaultMessageNotificationLevel; + /// {@template explicit_content_filter_level} + /// The explicit content filter level of the guild. + /// {@endtemplate} ExplicitContentFilterLevel? explicitContentFilterLevel; + /// The default roles of the guild. List? roles; + /// The default channels of the guild. List? channels; + /// {@template afk_channel_id} + /// The id of the afk channel. + /// {@endtemplate} + // TODO: Add an `id` field on ChannelBuilder. Snowflake? afkChannelId; + /// {@template afk_timeout} + /// The afk timeout of the guild. + /// {@endtemplate} Duration? afkTimeout; + /// {@template system_channel_id} + /// The id of the channel where guild notices such as welcome messages and boost events are posted. + /// {@endtemplate} + // TODO: Same as above. Snowflake? systemChannelId; + /// {@template system_channel_flags} + /// The default system channel flags. + /// {@endtemplate} Flags? systemChannelFlags; GuildBuilder({ @@ -63,42 +94,61 @@ class GuildBuilder extends CreateBuilder { } class GuildUpdateBuilder extends UpdateBuilder { + /// {@macro guild_name} String? name; + /// {@macro guild_verification_level} VerificationLevel? verificationLevel; + /// {@macro guild_default_message_notification_level} MessageNotificationLevel? defaultMessageNotificationLevel; + /// {@macro explicit_content_filter_level} ExplicitContentFilterLevel? explicitContentFilterLevel; + /// {@macro afk_channel_id} Snowflake? afkChannelId; + /// {@macro afk_timeout} Duration? afkTimeout; + /// {@macro guild_icon} ImageBuilder? icon; + /// The id of the new owner of the guild. Snowflake? newOwnerId; + /// The splash of the guild. ImageBuilder? splash; + /// The discovery splash of the guild. ImageBuilder? discoverySplash; + /// The banner of the guild. ImageBuilder? banner; + /// {@macro system_channel_id} Snowflake? systemChannelId; + /// {@macro system_channel_flags} Flags? systemChannelFlags; + /// The id of the rules channel. Snowflake? rulesChannelId; + /// The id of the public updates channel. Snowflake? publicUpdatesChannelId; + /// The preferred locale of the guild. Locale? preferredLocale; + /// The features of the guild. Flags? features; + /// The description of the guild. String? description; + /// Whether the premium progress bar is enabled. bool? premiumProgressBarEnabled; Snowflake? safetyAlertsChannelId; diff --git a/lib/src/models/channel/text_channel.dart b/lib/src/models/channel/text_channel.dart index d8d89f392..bb7b93303 100644 --- a/lib/src/models/channel/text_channel.dart +++ b/lib/src/models/channel/text_channel.dart @@ -38,7 +38,7 @@ class PartialTextChannel extends PartialChannel { //// A text channel abstract class TextChannel extends PartialTextChannel implements Channel { - /// The ID of the last [Message] snt in this channel, or `null` if no messages have been sent. + /// The ID of the last [Message] sent in this channel, or `null` if no messages have been sent. Snowflake? get lastMessageId; /// The rate limit duration per user. diff --git a/lib/src/models/message/message.dart b/lib/src/models/message/message.dart index e730098c8..ce9fac63b 100644 --- a/lib/src/models/message/message.dart +++ b/lib/src/models/message/message.dart @@ -57,12 +57,12 @@ class PartialMessage extends WritableSnowflakeEntity { /// Creates a reaction on this message. /// ```dart - /// await message.react('👍'); + /// await message.react(ReactionBuilder(name: '👍', id: null)); /// ``` /// or /// ```dart /// final emoji = await client.emoji.fetch(Snowflake(123456789012345678)); - /// await message.react(emoji.toString()); + /// await message.react(ReactionBuilder.fromEmoji(emoji)); /// ``` Future react(ReactionBuilder emoji) => manager.addReaction(id, emoji);