diff --git a/src/Discord.Net/DiscordClient.cs b/src/Discord.Net/DiscordClient.cs index c74faf03a..9e5c59a43 100644 --- a/src/Discord.Net/DiscordClient.cs +++ b/src/Discord.Net/DiscordClient.cs @@ -582,7 +582,8 @@ namespace Discord } //Auth - public async Task Connect(string token) + /// Connects to the Discord server with the provided token. + public async Task Connect(string token) { _isStopping.Reset(); @@ -590,8 +591,9 @@ namespace Discord await _webSocket.ConnectAsync(Endpoints.WebSocket_Hub, true); _isReady = true; - return token; } + /// Connects to the Discord server with the provided email and password. + /// Returns a token for future connections. public async Task Connect(string email, string password) { _isStopping.Reset(); @@ -608,17 +610,22 @@ namespace Discord _isReady = true; return response.Token; } + /// Connects to the Discord server with the provided token, and will fall back to username and password. + /// Returns a token for future connections. public async Task Connect(string email, string password, string token) { try { - return await Connect(token); + await Connect(token); + return token; } catch (InvalidOperationException) //Bad Token { return await Connect(email, password); } } + /// Connects to the Discord server as an anonymous user with the provided username. + /// Returns a token for future connections. public async Task ConnectAnonymous(string username) { _isStopping.Reset(); @@ -635,6 +642,7 @@ namespace Discord _isReady = true; return response.Token; } + /// Disconnects from the Discord server, canceling any pending requests. public async Task Disconnect() { _isReady = false; @@ -649,14 +657,17 @@ namespace Discord } //Servers + /// Creates a new server with the provided name and region (see Regions). public async Task CreateServer(string name, string region) { CheckReady(); var response = await DiscordAPI.CreateServer(name, region); return _servers.Update(response.Id, response); } + /// Leaves the provided server, destroying it if you are the owner. public Task LeaveServer(Server server) => LeaveServer(server.Id); + /// Leaves the provided server, destroying it if you are the owner. public async Task LeaveServer(string serverId) { CheckReady(); @@ -669,25 +680,31 @@ namespace Discord } //Channels + /// Creates a new channel with the provided name and type (see ChannelTypes). public Task CreateChannel(Server server, string name, string type) => CreateChannel(server.Id, name, type); - public async Task CreateChannel(string serverId, string name, string type) + /// Creates a new channel with the provided name and type (see ChannelTypes). + public async Task CreateChannel(string serverId, string name, string type) { CheckReady(); var response = await DiscordAPI.CreateChannel(serverId, name, type); return _channels.Update(response.Id, serverId, response); } + /// Creates a new private channel with the provided user. public Task CreatePMChannel(User user) => CreatePMChannel(user.Id); - public async Task CreatePMChannel(string recipientId) + /// Creates a new private channel with the provided user. + public async Task CreatePMChannel(string userId) { CheckReady(); - var response = await DiscordAPI.CreatePMChannel(UserId, recipientId); + var response = await DiscordAPI.CreatePMChannel(UserId, userId); return _channels.Update(response.Id, response); } + /// Destroys the provided channel. public Task DestroyChannel(Channel channel) => DestroyChannel(channel.Id); - public async Task DestroyChannel(string channelId) + /// Destroys the provided channel. + public async Task DestroyChannel(string channelId) { CheckReady(); try @@ -699,23 +716,31 @@ namespace Discord } //Bans + /// Bans a user from the provided server. public Task Ban(Server server, User user) => Ban(server.Id, user.Id); + /// Bans a user from the provided server. public Task Ban(Server server, string userId) => Ban(server.Id, userId); + /// Bans a user from the provided server. public Task Ban(string server, User user) => Ban(server, user.Id); + /// Bans a user from the provided server. public Task Ban(string serverId, string userId) { CheckReady(); return DiscordAPI.Ban(serverId, userId); } + /// Unbans a user from the provided server. public Task Unban(Server server, User user) => Unban(server.Id, user.Id); + /// Unbans a user from the provided server. public Task Unban(Server server, string userId) => Unban(server.Id, userId); + /// Unbans a user from the provided server. public Task Unban(string server, User user) => Unban(server, user.Id); + /// Unbans a user from the provided server. public async Task Unban(string serverId, string userId) { CheckReady(); @@ -727,15 +752,30 @@ namespace Discord } //Invites + /// Creates a new invite to the default channel of the provided server. + /// Time (in seconds) until the invite expires. Set to 0 to never expire. + /// If true, a user accepting this invite will be kicked from the server after closing their client. + /// If true, creates a human-readable link. Not supported if maxAge is set to 0. + /// The max amount of times this invite may be used. public Task CreateInvite(Server server, int maxAge, int maxUses, bool isTemporary, bool hasXkcdPass) { return CreateInvite(server.DefaultChannelId, maxAge, maxUses, isTemporary, hasXkcdPass); } + /// Creates a new invite to the provided channel. + /// Time (in seconds) until the invite expires. Set to 0 to never expire. + /// If true, a user accepting this invite will be kicked from the server after closing their client. + /// If true, creates a human-readable link. Not supported if maxAge is set to 0. + /// The max amount of times this invite may be used. public Task CreateInvite(Channel channel, int maxAge, int maxUses, bool isTemporary, bool hasXkcdPass) { return CreateInvite(channel, maxAge, maxUses, isTemporary, hasXkcdPass); } - public async Task CreateInvite(string channelId, int maxAge, int maxUses, bool isTemporary, bool hasXkcdPass) + /// Creates a new invite to the provided channel. + /// Time (in seconds) until the invite expires. Set to 0 to never expire. + /// If true, a user accepting this invite will be kicked from the server after closing their client. + /// If true, creates a human-readable link. Not supported if maxAge is set to 0. + /// The max amount of times this invite may be used. + public async Task CreateInvite(string channelId, int maxAge, int maxUses, bool isTemporary, bool hasXkcdPass) { CheckReady(); var response = await DiscordAPI.CreateInvite(channelId, maxAge, maxUses, isTemporary, hasXkcdPass); @@ -754,7 +794,9 @@ namespace Discord Uses = response.Uses }; } - public async Task GetInvite(string id) + /// Gets more info about the provided invite. + /// Supported formats: inviteCode, xkcdCode, https://discord.gg/inviteCode, https://discord.gg/xkcdCode + public async Task GetInvite(string id) { CheckReady(); var response = await DiscordAPI.GetInvite(id); @@ -765,11 +807,13 @@ namespace Discord ServerId = response.Server.Id }; } + /// Accepts the provided invite. public Task AcceptInvite(Invite invite) { CheckReady(); return DiscordAPI.AcceptInvite(invite.Code); } + /// Accepts the provided invite. public async Task AcceptInvite(string id) { CheckReady(); @@ -786,6 +830,7 @@ namespace Discord var response = await DiscordAPI.GetInvite(id); await DiscordAPI.AcceptInvite(response.Code); } + /// Deletes the provided invite. public async Task DeleteInvite(string id) { CheckReady(); @@ -799,13 +844,19 @@ namespace Discord } //Chat + /// Sends a message to the provided channel. public Task SendMessage(Channel channel, string text) => SendMessage(channel.Id, text, new string[0]); + /// Sends a message to the provided channel. public Task SendMessage(string channelId, string text) => SendMessage(channelId, text, new string[0]); + /// Sends a message to the provided channel, mentioning certain users. + /// While not required, it is recommended to include a mention reference in the text (see User.Mention). public Task SendMessage(Channel channel, string text, string[] mentions) => SendMessage(channel.Id, text, mentions); - public async Task SendMessage(string channelId, string text, string[] mentions) + /// Sends a message to the provided channel, mentioning certain users. + /// While not required, it is recommended to include a mention reference in the text (see User.Mention). + public async Task SendMessage(string channelId, string text, string[] mentions) { CheckReady(); @@ -829,16 +880,25 @@ namespace Discord } } + /// Edits a message the provided message. public Task EditMessage(Message message, string text) => EditMessage(message.ChannelId, message.Id, text, new string[0]); + /// Edits a message the provided message. public Task EditMessage(Channel channel, string messageId, string text) => EditMessage(channel.Id, messageId, text, new string[0]); + /// Edits a message the provided message. public Task EditMessage(string channelId, string messageId, string text) => EditMessage(channelId, messageId, text, new string[0]); + /// Edits a message the provided message, mentioning certain users. + /// While not required, it is recommended to include a mention reference in the text (see User.Mention). public Task EditMessage(Message message, string text, string[] mentions) => EditMessage(message.ChannelId, message.Id, text, mentions); + /// Edits a message the provided message, mentioning certain users. + /// While not required, it is recommended to include a mention reference in the text (see User.Mention). public Task EditMessage(Channel channel, string messageId, string text, string[] mentions) => EditMessage(channel.Id, messageId, text, mentions); + /// Edits a message the provided message, mentioning certain users. + /// While not required, it is recommended to include a mention reference in the text (see User.Mention). public async Task EditMessage(string channelId, string messageId, string text, string[] mentions) { CheckReady(); @@ -849,8 +909,10 @@ namespace Discord _messages.Update(msg.Id, channelId, msg); } + /// Deletes the provided message. public Task DeleteMessage(Message msg) => DeleteMessage(msg.ChannelId, msg.Id); + /// Deletes the provided message. public async Task DeleteMessage(string channelId, string msgId) { try @@ -863,12 +925,18 @@ namespace Discord return null; } + /// Sends a file to the provided channel. public Task SendFile(Channel channel, string path) => SendFile(channel.Id, path); + /// Sends a file to the provided channel. public Task SendFile(string channelId, string path) => SendFile(channelId, File.OpenRead(path), Path.GetFileName(path)); + /// Reads a stream and sends it to the provided channel as a file. + /// It is highly recommended that this stream be cached in memory or on disk, or the request may time out. public Task SendFile(Channel channel, Stream stream, string filename = null) => SendFile(channel.Id, stream, filename); + /// Reads a stream and sends it to the provided channel as a file. + /// It is highly recommended that this stream be cached in memory or on disk, or the request may time out. public Task SendFile(string channelId, Stream stream, string filename = null) { return DiscordAPI.SendFile(channelId, stream, filename); @@ -876,48 +944,64 @@ namespace Discord //Voice + /// Mutes a user on the provided server. public Task Mute(Server server, User user) => Mute(server.Id, user.Id); + /// Mutes a user on the provided server. public Task Mute(Server server, string userId) => Mute(server.Id, userId); + /// Mutes a user on the provided server. public Task Mute(string server, User user) => Mute(server, user.Id); + /// Mutes a user on the provided server. public Task Mute(string serverId, string userId) { CheckReady(); return DiscordAPI.Mute(serverId, userId); } + /// Unmutes a user on the provided server. public Task Unmute(Server server, User user) => Unmute(server.Id, user.Id); + /// Unmutes a user on the provided server. public Task Unmute(Server server, string userId) => Unmute(server.Id, userId); + /// Unmutes a user on the provided server. public Task Unmute(string server, User user) => Unmute(server, user.Id); + /// Unmutes a user on the provided server. public Task Unmute(string serverId, string userId) { CheckReady(); return DiscordAPI.Unmute(serverId, userId); } + /// Deafens a user on the provided server. public Task Deafen(Server server, User user) => Deafen(server.Id, user.Id); + /// Deafens a user on the provided server. public Task Deafen(Server server, string userId) => Deafen(server.Id, userId); + /// Deafens a user on the provided server. public Task Deafen(string server, User user) => Deafen(server, user.Id); + /// Deafens a user on the provided server. public Task Deafen(string serverId, string userId) { CheckReady(); return DiscordAPI.Deafen(serverId, userId); } + /// Undeafens a user on the provided server. public Task Undeafen(Server server, User user) => Undeafen(server.Id, user.Id); + /// Undeafens a user on the provided server. public Task Undeafen(Server server, string userId) => Undeafen(server.Id, userId); + /// Undeafens a user on the provided server. public Task Undeafen(string server, User user) => Undeafen(server, user.Id); + /// Undeafens a user on the provided server. public Task Undeafen(string serverId, string userId) { CheckReady(); @@ -925,18 +1009,21 @@ namespace Discord } //Profile + /// Changes your username to newName. public async Task ChangeUsername(string newName, string currentEmail, string currentPassword) { CheckReady(); var response = await DiscordAPI.ChangeUsername(newName, currentEmail, currentPassword); _users.Update(response.Id, response); } + /// Changes your email to newEmail. public async Task ChangeEmail(string newEmail, string currentPassword) { CheckReady(); var response = await DiscordAPI.ChangeEmail(newEmail, currentPassword); _users.Update(response.Id, response); } + /// Changes your password to newPassword. public async Task ChangePassword(string newPassword, string currentEmail, string currentPassword) { CheckReady();