Better synchronize model types with Discord API documentation

[kangalio]

trafficstars

It's a chore to use model types because

• they're missing some fields
• they have some redundant Option<T> fields that users think they can use but they're just always None
• other fields have lacking docs (e.g. Option<T> fields not mentioning they're only sometimes populated, leaving users confused)

All of this could be solved by better integrating the official Discord API docs into serenity.

I think all model types should include a link to the official object structure docs (like #1965).

Ideally, we would also have a tool that parses serenity source code using syn and scrapes Discord API docs, to make sure serenity's model types have correct fields and include Discord's official field documentation

[kangalio]

Ideally, we would also have a tool that parses serenity source code using syn and scrapes Discord API docs, to make sure serenity's model types have correct fields and include Discord's official field documentation

This is not really doable because our structs differ from official Discord docs too often. For example representing mutually exclusive fields via enums instead of flattened nullable fields or inserting additional data like guild_id.

[kangalio]

Also, such a tool isn't needed because Discord announces new API features. So we'd only need to invest a one-time effort of going through all structs and updating them according to the Discord API docs; and after that it's just a matter of keeping up with the announcements.

Plan

• go through model structs systematically,
• look at the associated Discord docs page (should be linked in the struct doc comments; insert link if not)
• sort the struct fields in the same order as in Discord docs for easier comparability
• add missing struct fields
• remove phantom struct fields
  • beware for exceptions! Some structs have a guild_id field that is inserted at deserialization time. Such exceptions should be commented in the struct