document the poll result message and embed #7050
Conversation
anderswift
force-pushed
the
document-poll-result
branch
from
d033fd6 to
ca475bc
Compare
anderswift
force-pushed
the
document-poll-result
branch
3 times, most recently
from
ad256f6 to
1a0a738
Compare
anderswift
force-pushed
the
document-poll-result
branch
from
1a0a738 to
ced77a3
Compare
anderswift
requested review from
colinloretz and
DV8FromTheWorld
and removed request for
a team
Co-authored-by: val.le <81811276+valdotle@users.noreply.github.com>
docs/resources/Message.md
Outdated
| - `poll_question_text` contains the question text from the original poll message. | ||
| - `victor_answer_votes` contains the number of votes for the answer(s) with the most votes. | ||
| - `total_votes` contains the total number of votes in the poll. | ||
| - `victor_answer_id` contains the id for the winning answer, if applicable. | ||
| - `victor_answer_text` contains the text for the winning answer, if applicable. | ||
| - `victor_answer_emoji_id` contains the id for the emoji associated with the winning answer, if applicable. | ||
| - `victor_answer_emoji_name` contains the name of the emoji associated with the winning answer, if applicable. | ||
| - `victor_answer_emoji_animated` specifies whether the emoji associated with the winning answer is animated, if applicable. |
There was a problem hiding this comment.
should we put this in a table so it's more readable?
There was a problem hiding this comment.
Would be cleaner. Yes please 🙏
There was a problem hiding this comment.
should we put this in a table so it's more readable?
I gave this whole documentation some more thought, and I think it could use some major changes:
I agree a table would probably be better than this list. But I think the whole embed documentation warrants a separate section and probably a code sample in addition to the table, since this format / way to use embeds (thankfully) isn't widespread.
This, in combination with some improvements to the wording would go a long way to clarify how poll result embeds are structured:
"embed that can have the following fields" should probably be changed to something like "embed field objects that can have the following names/entries/..." in combination with some mention of key-value pairs using the embed field name and value fields respectively.
From my understanding, the whole message reference content attribution section acts as a list of how different message types utilize the message reference object and not as an info dump. Hence why I'd consider the majority of the poll result message documentation off-topic for this section...
There was a problem hiding this comment.
yeah this part about the embed fields should be in a new section in the embed object documentation. and we should add the automod embeds there later
There was a problem hiding this comment.
sorry, i've been on vacation but just made some updates based on this feedback. i do agree that the specific embed fields for each type warrants a new section. i didn't want to take on documenting fields for some of the other embed types here, but i can at least get it started and we can flesh this out in another PR.
anderswift
force-pushed
the
document-poll-result
branch
3 times, most recently
from
a3256bd to
65b83a1
Compare
anderswift
force-pushed
the
document-poll-result
branch
from
65b83a1 to
144fe78
Compare
| @@ -510,6 +517,23 @@ Additionally, the combined sum of characters in all `title`, `description`, `fie | |||
|
|
|||
| Embeds are deduplicated by URL. If a message contains multiple embeds with the same URL, only the first is shown. | |||
|
|
|||
| #### Embed Fields by Embed Type | |||
|
|
|||
| Certain embed types are used to power special UIs. These embeds use [fields](#DOCS_RESOURCES_MESSAGE/embed-object-embed-field-structure) to include additional data in key-value pairs. Below is a reference of possible embed fields for each of the following embed types. | |||
There was a problem hiding this comment.
| Certain embed types are used to power special UIs. These embeds use [fields](#DOCS_RESOURCES_MESSAGE/embed-object-embed-field-structure) to include additional data in key-value pairs. Below is a reference of possible embed fields for each of the following embed types. | |
| Certain embed types are used to power special UIs. These embeds use [embed fields](#DOCS_RESOURCES_MESSAGE/embed-object-embed-field-structure) to include additional data in key-value pairs. Consequently, values will always be strings. | |
| Below is a reference of possible embed fields for each of the following embed types. |
docs/resources/Message.md
Outdated
|
|
||
| ###### Poll Result Embed Fields | ||
|
|
||
| | Embed Field Name | Embed Field Value Description | |
There was a problem hiding this comment.
Maybe a "parse as" (or something like that) column could be added to indicate what the value string will look like.
Additionally, a code sample would probably still help to visualize the explanation given above.
Documents the poll result message and embed.