Inconsistent documentation in the Api module

[skippi]

Like #49 , this is another issue for tracking changes that we do while working on fixing the Api. After the Api work is done, all Api functions should have the following documentation format:

• Each @doc attribute should use the ~S sigil.
• Each section is to be separated by a line break.
• Each code blocked section will use fenced code block markdown with the backtick symbols (`) instead of indentation. It will also specify the elixir language.
• The first section contains the endpoint's purpose. It will not have a header.
• The second section contains the endpoint's required permissions and fired gateway events (if applicable). It will not have a header. Endpoint specific details may go here if applicable.
• The third section contains the function's return values. It should be kept simple. It will not have a header.
• The fourth section contains the endpoint's JSON params, if applicable. It will have a header. The header will be labeled as "Options". This section will also mention any required options as a final section note.
• The fifth section contains the function's examples. This section should disclose confusion on how the function can be used. It will contain a header.
  • Alternatively, if a function will point to another function for examples, the example section will be moved beneath the return value section. In this case, the example will not have a header.

Here an example template for the create_guild_emoji/2 function.

@doc ~S"""
Creates a new emoji for the given guild.

This endpoint requires the `MANAGE_EMOJIS` permission. It fires the `GUILD_EMOJIS_UPDATE` event.

If successful, returns `{:ok, emoji}`. Otherwise, returns a `t:Nostrum.Api.error/0`.

## Options

  * `:name` (string) - name of the emoji
  * `:image` (base64 data URI) - the 128x128 emoji image. Maximum size of 256kb
  * `:roles` (list of `t:Nostrum.Struct.Snowflake.t/0`) - roles for which this emoji will be whitelisted
    (default: [])

  `:name` and `:image` are always required.

## Examples

```Elixir
image = "data:image/png;base64,YXl5IGJieSB1IGx1a2luIDQgc3VtIGZ1az8="

Nostrum.Api.create_guild_emoji(43189401384091, name: "nostrum", image: image, roles: [])
```
"""

An example for delete_own_reaction/3:

@doc ~S"""
Deletes a reaction made by the user.

If succesful, returns `{:ok}`. Otherwise, returns `t:Nostrum.Api.error/0`.

See `create_reaction/3` for similar examples.
"""

Concerns and Solutions

1. Some API functions, like Nostrum.Api.get_user/1 are obsolete due to nostrum already having a cache. Shouldn't we document that these functions are obsolete?

We will be addressing this by mentioning the cache and its usage in the Api module doc.

Known inconsistencies

• User related Api functions.