From 09791c75d4fb3d2c53dfe83e590e774c7fe7a8a5 Mon Sep 17 00:00:00 2001
From: Joe Banks <joe@jb3.dev>
Date: Sun, 14 Apr 2024 14:45:23 +0100
Subject: [PATCH] Add documentation for helper methods on Poll

---
 lib/nostrum/struct/message/poll.ex        | 32 +++++++++++++++++++++++
 lib/nostrum/struct/message/poll/answer.ex |  2 +-
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/lib/nostrum/struct/message/poll.ex b/lib/nostrum/struct/message/poll.ex
index e0ecbc43c..ce1dc4620 100644
--- a/lib/nostrum/struct/message/poll.ex
+++ b/lib/nostrum/struct/message/poll.ex
@@ -5,6 +5,7 @@ defmodule Nostrum.Struct.Message.Poll do
 
   alias Nostrum.Util
 
+  alias Nostrum.Snowflake
   alias Nostrum.Struct.Message.Poll.{Answer, MediaObject, Results}
 
   @derive Jason.Encoder
@@ -76,6 +77,27 @@ defmodule Nostrum.Struct.Message.Poll do
     struct(__MODULE__, new)
   end
 
+  @doc ~S"""
+  Helper method to create a new poll.
+
+  Accepts a `question_text` parameter which is the string to use as the poll title.
+
+  Keyword arguments:
+  - duration: duration (in hours) the poll should be open for
+  - allow_multiselect: whether users should be able to select multiple answers
+
+  You can also pass an `answers` key with answers, though `put_answer/2` and `put_answer/3` are advised.
+
+  ## Examples
+
+  ```elixir
+  poll = Poll.create_poll("Do you enjoy pineapple on pizza?", duration: 2, allow_multiselect: false)
+          |> Poll.put_answer("Yes!", default_emoji: "\u2705") # check mark emoji
+          |> Poll.put_answer("No!", default_emoji: "\u274C") # cross emoji
+
+  Api.create_message(channel_id, poll: poll)
+  ```
+  """
   @spec create_poll(String.t(), duration: duration, allow_multiselect: allow_multiselect) :: t()
   def create_poll(question_text, duration: duration, allow_multiselect: allow_multiselect) do
     %__MODULE__{
@@ -108,6 +130,14 @@ defmodule Nostrum.Struct.Message.Poll do
     Map.update(poll, :answers, [answer], fn answers -> answers ++ [answer] end)
   end
 
+  @doc ~S"""
+  Add an answer to the provided poll, see `create_poll/2` for a code sample of this function.
+
+  Takes a required "answer" text field, as well as either of the optional arguments:
+  - `custom_emoji`: An integer representing the snowflake of an emoji to display with the option
+  - `default_emoji`: A default platform emoji represented as a unicode character
+  """
+  @spec put_answer(t(), String.t()) :: t()
   def put_answer(poll, answer) do
     new_answer = %Answer{
       poll_media: %MediaObject{
@@ -118,6 +148,7 @@ defmodule Nostrum.Struct.Message.Poll do
     add_answer(poll, new_answer)
   end
 
+  @spec put_answer(t(), String.t(), custom_emoji: Snowflake.t()) :: t()
   def put_answer(poll, answer, custom_emoji: custom_emoji) do
     new_answer = %Answer{
       poll_media: %MediaObject{
@@ -131,6 +162,7 @@ defmodule Nostrum.Struct.Message.Poll do
     add_answer(poll, new_answer)
   end
 
+  @spec put_answer(t(), String.t(), default_emoji: String.t()) :: t()
   def put_answer(poll, answer, default_emoji: default_emoji) do
     new_answer = %Answer{
       poll_media: %MediaObject{
diff --git a/lib/nostrum/struct/message/poll/answer.ex b/lib/nostrum/struct/message/poll/answer.ex
index aecabe954..11e07236b 100644
--- a/lib/nostrum/struct/message/poll/answer.ex
+++ b/lib/nostrum/struct/message/poll/answer.ex
@@ -19,7 +19,7 @@ defmodule Nostrum.Struct.Message.Poll.Answer do
   @type answer_id :: integer | nil
 
   @typedoc """
-
+  Object representing how the answer is displayed visually, with the text and optional emojis.
   """
   @type poll_media :: MediaObject.t()