[Docs] Document Polls (#2930)

* poll docs

* oopsie

docs/guides/polls/polls.md

@@ -0,0 +1,61 @@
+---
+uid: Guides.Polls
+title: Polls
+---
+
+# Polls in Discord.Net
+
+Polls are... Polls! 
+
+![example poll](images/poll.png)
+
+This guide will explain how to use polls in your applications.
+
+> [!NOTE]
+> To get contents of polls sent by users other than your bot you need to enable `GatewayIntent.MessageContent` intent.
+
+## Creating polls
+
+A poll is part of a message; to send one you need to pass a [PollProperties] object into the `poll` parameter of any method that can be used to send messages. (ex. `SendMessageAsync`, `RespondAsync`, etc)
+
+[!code-csharp[Creating polls](samples/create-poll.cs)]
+
+> [!WARNING]
+> Due to limitations of the Discord API it's not possible to send attachments in a messages with a poll.
+
+> [!NOTE]
+> It is not possible to modify polls after them being created.
+
+
+## Managing polls
+
+### Ending polls
+You can expire polls early by calling `EndPollAsync` on an [IUserMessage] with a poll.
+
+[!code-csharp[Ending polls](samples/end-poll.cs)]
+
+### Getting poll answer voters
+To get voters for a specific answer call `GetPollAnswerVotersAsync(answerId)` on an [IUserMessage] with a poll.
+
+[!code-csharp[Getting poll answer voters](samples/get-poll-voters.cs)]
+
+### Retrieving poll results
+You can get results of a poll by simply getting an [IUserMessage] and checking the `IUserMessage.Poll.Results` property. Alteratively you can check the results on a `MessageUpdated` gateway event.
+
+
+## Gateway events
+
+### Poll votes
+You can receive information about poll votes live using following events:
+- `PollVoteAdded`
+- `PollVoteRemoved`
+
+> [!NOTE]
+> These events are only sent if the client has `GatewayIntents.GuildMessagePolls` or `GatewayIntents.DirectMessagePolls` intents enabled. It will receive events for polls in guild or dm channels respectively.
+
+### Poll expiry
+On poll expiry the `MessageUpdated` event is fired.
+
+
+[PollProperties]: xref:Discord.PollProperties
+[IUserMessage]: xref:Discord.IUserMessage

docs/guides/polls/samples/create-poll.cs

@@ -0,0 +1,40 @@
+
+// Create a poll
+var poll = new PollProperties
+{
+    // Set the question
+    Question = new ()
+    {   // Text of the question
+        Text = "Discord.Net is awesome!"
+    },
+    // Set the duration of the poll in hours
+    Duration = 69,
+    // Add answers to the poll
+    // You can add from 1 to 10 answers
+    Answers = [
+        // An answer can consist of text and an emoji
+        new PollMediaProperties
+        {   // Text for the answer
+            Text = "Yes!",
+            // Emoji for the answer
+            // Can be a custom emoji or unicode one
+            // Remember that bot must be in the guild where the custom emoji is
+            Emoji = Emote.Parse("<:wires:1214532316999974962>")
+        },
+        // Or just text
+        new PollMediaProperties
+        {
+            Text = "Of course!",
+        }
+        ],
+    // You can allow users to select multiple answers
+    // By default, it's set to false
+    AllowMultiselect = true,
+    // Also you can set the layout of the poll
+    // By default, it's set to Default
+    // At this time, it's the only available layout type
+    LayoutType = PollLayout.Default
+};
+
+// Send the poll to the text channel
+await textChannel.SendMessageAsync(poll: poll);

docs/guides/polls/samples/end-poll.cs

@@ -0,0 +1,4 @@
+// Get a message with a poll
+var message = await channel.GetMessageAsync(id) as IUserMessage;
+// End the poll
+await message.EndPollAsync();

docs/guides/polls/samples/get-poll-voters.cs

@@ -0,0 +1,4 @@
+// Get the id of the first answer in the poll
+var answerId = message.Poll.Answers.First().AnswerId;
+// Get the list of voters who voted for the first answer
+var voters = await message.GetPollAnswerVotersAsync(answerId).FlattenAsync();

docs/guides/toc.yml

@@ -130,5 +130,7 @@
   topicUid: Guides.BearerToken
 - name: Voice
   topicUid: Guides.Voice.SendingVoice
+- name: Polls
+  topicUid: Guides.Polls
 - name: Deployment
   topicUid: Guides.Deployment