Add more docs

19 files changed, 151 insertions, 92 deletions

diff --git a/lib/models/emoji.ml b/lib/models/emoji.ml
index 9debfe2..4d33615 100644
--- a/lib/models/emoji.ml
+++ b/lib/models/emoji.ml
@@ -10,7 +10,7 @@ type t = {
     name: string;
     roles: Role_id.t list [@default []];
     user: User_t.t option [@default None];
-    require_colons: bool option [@default None];
-    managed: bool option [@default None];
-    animated: bool option [@default None];
+    require_colons: bool [@default false];
+    managed: bool [@default false];
+    animated: bool [@default false];
 } [@@deriving sexp, yojson { strict = false}]
\ No newline at end of file
diff --git a/lib/models/emoji.mli b/lib/models/emoji.mli
index 10b12d5..1660719 100644
--- a/lib/models/emoji.mli
+++ b/lib/models/emoji.mli
@@ -1,14 +1,16 @@
+(** A partial emoji, used internally. *)
 type partial_emoji = {
     id: Snowflake.t option;
     name: string;
 } [@@deriving sexp, yojson]
 
+(** A full emoji object. *)
 type t = {
-    id: Snowflake.t option;
-    name: string;
-    roles: Role_id.t list;
-    user: User_t.t option;
-    require_colons: bool option;
-    managed: bool option;
-    animated: bool option;
+    id: Snowflake.t option; (** Snowflake ID of the emoji. Only exists for custom emojis. *)
+    name: string; (** Name of the emoji. Either the emoji custom name or a unicode character. *)
+    roles: Role_id.t list;  (** List of roles required to use this emoji. Is only non-empty on some integration emojis. *)
+    user: User_t.t option;  (** User object of the person who uploaded the emoji. Only exists for custom emojis. *)
+    require_colons: bool; (** Whether the emoji must be wrapped in colons. Is false for unicode emojis. *)
+    managed: bool; (** Whether the emoji is managed by an integration. *)
+    animated: bool; (** Whether the emoji is animated. *)
 } [@@deriving sexp, yojson]
\ No newline at end of file
diff --git a/lib/models/guild/ban_t.ml b/lib/models/guild/ban_t.ml
index b49eefc..7923b58 100644
--- a/lib/models/guild/ban_t.ml
+++ b/lib/models/guild/ban_t.ml
@@ -1,6 +1,6 @@
 open Core
 
 type t = {
-    reason: string [@default ""];
+    reason: string option [@default None];
     user: User_t.t;
 } [@@deriving sexp, yojson { strict = false}]
\ No newline at end of file
diff --git a/lib/models/guild/ban_t.mli b/lib/models/guild/ban_t.mli
index 95fb274..51d59e7 100644
--- a/lib/models/guild/ban_t.mli
+++ b/lib/models/guild/ban_t.mli
@@ -1,4 +1,4 @@
 type t = {
-    reason: string;
-    user: User_t.t;
+    reason: string option; (** The reason for the ban. *)
+    user: User_t.t; (** The banned user. *)
 } [@@deriving sexp, yojson]
\ No newline at end of file
diff --git a/lib/models/guild/guild.mli b/lib/models/guild/guild.mli
index 81055a1..e6f272c 100644
--- a/lib/models/guild/guild.mli
+++ b/lib/models/guild/guild.mli
@@ -4,6 +4,11 @@ include module type of Guild_t
 include S.GuildImpl with
     type t := Guild_t.t
 
+(** Get a channel belonging to this guild. This does not make an HTTP request. *)
 val get_channel : id:Channel_id_t.t -> t -> Channel_t.t Deferred.Or_error.t
+
+(** Get a member belonging to this guild. This does not make an HTTP request. *)
 val get_member : id:User_id_t.t -> t -> Member_t.t Deferred.Or_error.t
+
+(** Get a role belonging to this guild. This does not make an HTTP request. *)
 val get_role : id:Role_id.t -> t -> Role_t.t option
\ No newline at end of file
diff --git a/lib/models/guild/guild_t.ml b/lib/models/guild/guild_t.ml
index 42e373c..fa62a8f 100644
--- a/lib/models/guild/guild_t.ml
+++ b/lib/models/guild/guild_t.ml
@@ -13,7 +13,7 @@ type pre = {
     region: string;
     afk_channel_id: Channel_id_t.t option [@default None];
     afk_timeout: int;
-    embed_enabled: bool option [@default None];
+    embed_enabled: bool [@default false];
     embed_channel_id: Channel_id_t.t option [@default None];
     verification_level: int;
     default_message_notifications: int;
@@ -23,9 +23,9 @@ type pre = {
     features: string list;
     mfa_level: int;
     application_id: Snowflake.t option [@default None];
-    widget_enabled: bool option [@default None];
-    widget_channel: Channel_t.channel_wrapper option [@default None];
-    system_channel: Channel_t.channel_wrapper option [@default None];
+    widget_enabled: bool [@default false];
+    widget_channel_id: Channel_id_t.t option [@default None];
+    system_channel_id: Channel_id_t.t option [@default None];
     large: bool;
     unavailable: bool;
     member_count: int option [@default None];
@@ -42,7 +42,7 @@ type t = {
     region: string;
     afk_channel_id: Channel_id_t.t option [@default None];
     afk_timeout: int;
-    embed_enabled: bool option [@default None];
+    embed_enabled: bool [@default false];
     embed_channel_id: Channel_id_t.t option [@default None];
     verification_level: int;
     default_message_notifications: int;
@@ -52,9 +52,9 @@ type t = {
     features: string list;
     mfa_level: int;
     application_id: Snowflake.t option [@default None];
-    widget_enabled: bool option [@default None];
-    widget_channel: Channel_t.t option [@default None];
-    system_channel: Channel_t.t option [@default None];
+    widget_enabled: bool [@default false];
+    widget_channel_id: Channel_id_t.t option [@default None];
+    system_channel_id: Channel_id_t.t option [@default None];
     large: bool;
     unavailable: bool;
     member_count: int option [@default None];
@@ -62,13 +62,11 @@ type t = {
     channels: Channel_t.t list;
 } [@@deriving sexp, yojson { strict = false }]
 
-let wrap ({id;name;icon;splash;owner_id;region;afk_channel_id;afk_timeout;embed_enabled;embed_channel_id;verification_level;default_message_notifications;explicit_content_filter;roles;emojis;features;mfa_level;application_id;widget_enabled;widget_channel;system_channel;large;unavailable;member_count;members;channels}:pre) =
+let wrap ({id;name;icon;splash;owner_id;region;afk_channel_id;afk_timeout;embed_enabled;embed_channel_id;verification_level;default_message_notifications;explicit_content_filter;roles;emojis;features;mfa_level;application_id;widget_enabled;widget_channel_id;system_channel_id;large;unavailable;member_count;members;channels}:pre) =
     let `Guild_id id = id in
     let roles = List.map ~f:(Role_t.wrap ~guild_id:id) roles in
     let members = List.map ~f:(Member_t.wrap ~guild_id:id) members in
     let channels = List.map ~f:Channel_t.wrap channels in
-    let widget_channel = Option.map ~f:Channel_t.wrap widget_channel in
-    let system_channel = Option.map ~f:Channel_t.wrap system_channel in
-    {id = `Guild_id id;name;icon;splash;owner_id;region;afk_channel_id;afk_timeout;embed_enabled;embed_channel_id;verification_level;default_message_notifications;explicit_content_filter;roles;emojis;features;mfa_level;application_id;widget_enabled;widget_channel;system_channel;large;unavailable;member_count;members;channels}
+    {id = `Guild_id id;name;icon;splash;owner_id;region;afk_channel_id;afk_timeout;embed_enabled;embed_channel_id;verification_level;default_message_notifications;explicit_content_filter;roles;emojis;features;mfa_level;application_id;widget_enabled;widget_channel_id;system_channel_id;large;unavailable;member_count;members;channels}
 
 let get_id guild = let `Guild_id id = guild.id in id
\ No newline at end of file
diff --git a/lib/models/guild/guild_t.mli b/lib/models/guild/guild_t.mli
index 0b1ec92..e1c0718 100644
--- a/lib/models/guild/guild_t.mli
+++ b/lib/models/guild/guild_t.mli
@@ -2,6 +2,7 @@ type unavailable = {
     id: Guild_id_t.t;
 } [@@deriving sexp, yojson]
 
+(** Used internally. *)
 type pre = {
     id: Guild_id_t.t;
     name: string;
@@ -11,7 +12,7 @@ type pre = {
     region: string;
     afk_channel_id: Channel_id_t.t option;
     afk_timeout: int;
-    embed_enabled: bool option;
+    embed_enabled: bool;
     embed_channel_id: Channel_id_t.t option;
     verification_level: int;
     default_message_notifications: int;
@@ -21,9 +22,9 @@ type pre = {
     features: string list;
     mfa_level: int;
     application_id: Snowflake.t option;
-    widget_enabled: bool option;
-    widget_channel: Channel_t.channel_wrapper option;
-    system_channel: Channel_t.channel_wrapper option;
+    widget_enabled: bool;
+    widget_channel_id: Channel_id_t.t option;
+    system_channel_id: Channel_id_t.t option;
     large: bool;
     unavailable: bool;
     member_count: int option;
@@ -31,33 +32,34 @@ type pre = {
     channels: Channel_t.channel_wrapper list;
 } [@@deriving sexp, yojson]
 
+(** A Guild object *)
 type t = {
-    id: Guild_id_t.t;
-    name: string;
-    icon: string option;
-    splash: string option;
-    owner_id: User_id_t.t;
-    region: string;
-    afk_channel_id: Channel_id_t.t option;
-    afk_timeout: int;
-    embed_enabled: bool option;
-    embed_channel_id: Channel_id_t.t option;
-    verification_level: int;
-    default_message_notifications: int;
-    explicit_content_filter: int;
-    roles: Role_t.t list;
-    emojis: Emoji.t list;
-    features: string list;
-    mfa_level: int;
-    application_id: Snowflake.t option;
-    widget_enabled: bool option;
-    widget_channel: Channel_t.t option;
-    system_channel: Channel_t.t option;
-    large: bool;
-    unavailable: bool;
-    member_count: int option;
-    members: Member_t.t list;
-    channels: Channel_t.t list;
+    id: Guild_id_t.t; (** The guild's snowflake ID. *)
+    name: string; (** The guild name. *)
+    icon: string option; (** The guild icon hash, if one is set. *)
+    splash: string option; (** The guild splash hash, if one is set. *)
+    owner_id: User_id_t.t; (** The user ID of the owner. *)
+    region: string; (** The region the guild is in. *)
+    afk_channel_id: Channel_id_t.t option; (** The AFK channel ID, if one is set. *)
+    afk_timeout: int; (** The time before a user is moved to the AFK channel. *)
+    embed_enabled: bool; (** Whether the embed is enabled. *)
+    embed_channel_id: Channel_id_t.t option; (** The channel ID of the embed channel, if it is enabled. *)
+    verification_level: int; (** See {{:https://discordapp.com/developers/docs/resources/guild#guild-object-verification-level} the discord docs} for details. *)
+    default_message_notifications: int; (** 0 = All messages, 1 = Only mentions *)
+    explicit_content_filter: int; (** 0 = Disabled, 1 = For members with no roles, 2 = All members *)
+    roles: Role_t.t list; (** List of roles in the guild. *)
+    emojis: Emoji.t list; (** List of custom emojis in the guild. *)
+    features: string list; (** A List of features enabled for the guild. *)
+    mfa_level: int; (** 0 = None, 1 = Elevated *)
+    application_id: Snowflake.t option; (** Snowflake ID if the guild is bot-created. *)
+    widget_enabled: bool; (** Whether the widget is enabled. *)
+    widget_channel_id: Channel_id_t.t option; (** The channel ID for the widget, if enabled. *)
+    system_channel_id: Channel_id_t.t option; (** The channel ID where system messages are sent. *)
+    large: bool; (** Whether the guild exceeds the configured large threshold. *)
+    unavailable: bool; (** Whether the guild is unavailable or not. *)
+    member_count: int option; (** Total number of members in the guild. *)
+    members: Member_t.t list; (** List of guild members. *)
+    channels: Channel_t.t list; (** List of guild channels. *)
 } [@@deriving sexp, yojson]
 
 val wrap : pre -> t
diff --git a/lib/models/guild/member.mli b/lib/models/guild/member.mli
index 3ac786c..a3acc1b 100644
--- a/lib/models/guild/member.mli
+++ b/lib/models/guild/member.mli
@@ -2,11 +2,26 @@ open Async
 
 include module type of Member_t
 
+(** Adds a role to the member. *)
 val add_role : role:Role_t.t -> Member_t.t -> unit Deferred.Or_error.t
+
+(** Removes a role from the member. *)
 val remove_role : role:Role_t.t -> Member_t.t -> unit Deferred.Or_error.t
+
+(** Bans the member with optional reason and days of messages to delete. *)
 val ban : ?reason:string -> ?days:int -> Member_t.t -> unit Deferred.Or_error.t
+
+(** Kicks the member with the optional reason. *)
 val kick : ?reason:string -> Member_t.t -> unit Deferred.Or_error.t
+
+(** Mutes the member, preventing them from speaking in voice chats. *)
 val mute : Member_t.t -> unit Deferred.Or_error.t
+
+(** Deafens the member, preventing them from hearing others in voice chats. *)
 val deafen : Member_t.t -> unit Deferred.Or_error.t
+
+(** Opposite of {!mute}. *)
 val unmute : Member_t.t -> unit Deferred.Or_error.t
+
+(** Opposite of {!deafen}. *)
 val undeafen : Member_t.t -> unit Deferred.Or_error.t
\ No newline at end of file
diff --git a/lib/models/guild/member_t.mli b/lib/models/guild/member_t.mli
index 4f39b6c..918885e 100644
--- a/lib/models/guild/member_t.mli
+++ b/lib/models/guild/member_t.mli
@@ -27,14 +27,15 @@ type member_update = {
     nick: string option;
 } [@@deriving sexp, yojson]
 
+(** A member object. *)
 type t = {
-    nick: string option;
-    roles: Role_id.t list;
-    joined_at: string;
-    deaf: bool;
-    mute: bool;
-    user: User_t.t;
-    guild_id: Guild_id_t.t;
+    nick: string option; (** The nickname of the member, if they have one set. *)
+    roles: Role_id.t list; (** The roles the member has. *)
+    joined_at: string; (** An ISO8601 timestamp of when the user joined. *)
+    deaf: bool; (** Whether the user is deafened. *)
+    mute: bool; (** Whether the user is muted. *)
+    user: User_t.t; (** The underlying user object for the member. *)
+    guild_id: Guild_id_t.t; (** The guild ID in which the member exists. *)
 } [@@deriving sexp, yojson]
 
 val wrap : guild_id:Snowflake.t -> member -> t
\ No newline at end of file
diff --git a/lib/models/guild/role.mli b/lib/models/guild/role.mli
index 4c4f2a9..b311a60 100644
--- a/lib/models/guild/role.mli
+++ b/lib/models/guild/role.mli
@@ -2,10 +2,23 @@ open Async
 
 include module type of Role_t
 
-val allow_mention : t -> t Deferred.Or_error.t
+(** Deletes the role. This is permanent. *)
 val delete : t -> unit Deferred.Or_error.t
+
+(** Edits the role to allow mentions. *)
+val allow_mention : t -> t Deferred.Or_error.t
+
+(** Opposite of {!allow_mention} *)
 val disallow_mention : t -> t Deferred.Or_error.t
+
+(** Hoists the role. See {!Role.t.hoist}. *)
 val hoist : t -> t Deferred.Or_error.t
+
+(** Opposite of {!hoist}. *)
+val unhoist : t -> t Deferred.Or_error.t
+
+(** Sets the colour of the role. *)
 val set_colour : colour:int -> t -> t Deferred.Or_error.t
+
+(** Sets the name of the role. *)
 val set_name : name:string -> t -> t Deferred.Or_error.t
-val unhoist : t -> t Deferred.Or_error.t
\ No newline at end of file
diff --git a/lib/models/guild/role_t.mli b/lib/models/guild/role_t.mli
index 99517b8..6fd023f 100644
--- a/lib/models/guild/role_t.mli
+++ b/lib/models/guild/role_t.mli
@@ -1,3 +1,4 @@
+(** A role as Discord sends it. Only difference between this and {!t} is the lack of the guild_id field. *)
 type role = {
     id: Role_id.t;
     name: string;
@@ -9,16 +10,18 @@ type role = {
     mentionable: bool;
 } [@@deriving sexp, yojson]
 
+(** A role object. *)
 type t = {
-    id: Role_id.t;
-    name: string;
-    colour: int;
-    hoist: bool;
-    position: int;
-    permissions: int;
-    managed: bool;
-    mentionable: bool;
-    guild_id: Guild_id_t.t;
+    id: Role_id.t; (** The role's snowflake ID. *)
+    name: string; (** The role's name. *)
+    colour: int; (** The integer representation of the role colour. *)
+    hoist: bool; (** Whether the role is hoisted. This property controls whether the role is separated on the sidebar. *)
+    position: int; (** The position of the role. [@everyone] begins the list at 0. *)
+    permissions: int; (** The integer representation of the permissions the role has. *)
+    managed: bool; (** Whether the guild is managed by an integration. *)
+    mentionable: bool; (** Whether the role can be mentioned. *)
+    guild_id: Guild_id_t.t; (** The guild ID this role belongs to. *)
 } [@@deriving sexp, yojson]
 
+(** Convenience method to produce {!t} from {!role} and a snowflake. *)
 val wrap : guild_id:Snowflake.t -> role -> t
\ No newline at end of file
diff --git a/lib/models/snowflake.ml b/lib/models/snowflake.ml
index 4c87d63..3b55493 100644
--- a/lib/models/snowflake.ml
+++ b/lib/models/snowflake.ml
@@ -12,8 +12,11 @@ let to_yojson s : Yojson.Safe.json = `String (Int.to_string s)
 
 let timestamp snowflake = (snowflake lsr 22) + 1_420_070_400_000
 
-let timestamp_iso snowflake =
+let time_of_t snowflake =
     let t = timestamp snowflake |> float_of_int in
     Time.(Span.of_ms t
-    |> of_span_since_epoch
-    |> to_string_iso8601_basic ~zone:Zone.utc)
\ No newline at end of file
+    |> of_span_since_epoch)
+
+let timestamp_iso snowflake =
+    time_of_t snowflake
+    |> Time.(to_string_iso8601_basic ~zone:Zone.utc)
\ No newline at end of file
diff --git a/lib/models/snowflake.mli b/lib/models/snowflake.mli
index a6d42b5..e7f6be3 100644
--- a/lib/models/snowflake.mli
+++ b/lib/models/snowflake.mli
@@ -2,5 +2,11 @@ open Core
 
 type t = Int.t [@@deriving sexp, yojson]
 
+(** Convert a snowflake into a {!Core.Time.t} *)
+val time_of_t : t -> Time.t
+
+(** Convert a snowflake into a Unix timestamp. Millisecond precision. *)
 val timestamp : t -> int
+
+(** Convert a snowflake into an ISO8601 timestamp string. This is equivalent to calling [Snowflake.time_of_t snowflake |> Time.(to_string_iso8601_basic ~zone:Zone.utc)] *)
 val timestamp_iso : t -> string
\ No newline at end of file
diff --git a/lib/models/user/activity.ml b/lib/models/user/activity.ml
index 8e6ff80..c9b73d8 100644
--- a/lib/models/user/activity.ml
+++ b/lib/models/user/activity.ml
@@ -3,5 +3,5 @@ open Core
 type t = {
     name: string;
     kind: int [@key "type"];
-    url: string [@default ""];
+    url: string option [@default None];
 } [@@deriving sexp, yojson { strict = false}]
\ No newline at end of file
diff --git a/lib/models/user/activity.mli b/lib/models/user/activity.mli
index 53173b7..970ac59 100644
--- a/lib/models/user/activity.mli
+++ b/lib/models/user/activity.mli
@@ -1,5 +1,6 @@
+(** An activity object. *)
 type t = {
-    name: string;
-    kind: int;
-    url: string;
+    name: string; (** The name of the activity. *)
+    kind: int; (** 0 = Playing, 1 = Streaming, 2 = Listening, 3 = Watching *)
+    url: string option; (** Stream URL. Only validated for kind = 1. *)
 } [@@deriving sexp, yojson]
\ No newline at end of file
diff --git a/lib/models/user/presence.mli b/lib/models/user/presence.mli
index 13c8cf0..6c60d7f 100644
--- a/lib/models/user/presence.mli
+++ b/lib/models/user/presence.mli
@@ -1,8 +1,9 @@
+(** A user presence. *)
 type t = {
-    user: User_t.partial_user;
-    roles: Role_id.t list;
-    game: Activity.t option;
-    guild_id: Guild_id_t.t;
-    status: string;
-    activities: Activity.t list;
+    user: User_t.partial_user; (** A partial user that this presence belongs to. *)
+    roles: Role_id.t list; (** A list of roles that the user has. *)
+    game: Activity.t option; (** The current activity of the user, if any. *)
+    guild_id: Guild_id_t.t; (** The guild ID in which this presence exists. *)
+    status: string; (** One of [online], [idle], [offline], or [dnd]. *)
+    activities: Activity.t list; (** A list of all of the user's current activities. *)
 } [@@deriving sexp, yojson]
\ No newline at end of file
diff --git a/lib/models/user/user.mli b/lib/models/user/user.mli
index 6e2c0f1..d6050c2 100644
--- a/lib/models/user/user.mli
+++ b/lib/models/user/user.mli
@@ -1,6 +1,13 @@
 include module type of User_t
 
+(** The user tag. Equivalent to concatenating the username and discriminator, separated by a '#'. *)
 val tag : t -> string
+
+(** The mention string for the user. Equivalent to [<@USER_ID>]. *)
 val mention : t -> string
+
+(** The default avatar for the user. *)
 val default_avatar : t -> string
+
+(** The avatar url of the user, falling back to the default avatar. *)
 val face : t -> string
\ No newline at end of file
diff --git a/lib/models/user/user_t.mli b/lib/models/user/user_t.mli
index b0228f9..694fc1e 100644
--- a/lib/models/user/user_t.mli
+++ b/lib/models/user/user_t.mli
@@ -1,11 +1,13 @@
+(** A partial user. Used internally. *)
 type partial_user = {
     id: User_id_t.t;
 } [@@deriving sexp, yojson]
 
+(** A user object. *)
 type t = {
-    id: User_id_t.t;
-    username: string;
-    discriminator: string;
-    avatar: string option;
-    bot: bool;
+    id: User_id_t.t; (** The user's Snowflake ID, wrapped in the convenience [`User_id] type. *)
+    username: string; (** The username of the user. *)
+    discriminator: string; (** The 4 digits, as a string, that come after the '#' in a Discord username. *)
+    avatar: string option; (** The hash of the user avatar, if they have one set. See {!User.face} to get the avatar URL. *)
+    bot: bool; (** Whether the user is a bot. *)
 } [@@deriving sexp, yojson]
\ No newline at end of file
diff --git a/lib/s.ml b/lib/s.ml
index 64a3d17..85256cd 100644
--- a/lib/s.ml
+++ b/lib/s.ml
@@ -22,7 +22,7 @@ module type ChannelImpl = sig
             let check_command (msg : Message.t) =
                 if String.is_prefix ~prefix:"!hello" msg.content then
                     let embed = Embed.(default |> title "Hello World!") in
-                    Channel.send_message ~embed msg.channel >>> ignore
+                    Channel_id.send_message ~embed msg.channel_id >>> ignore
 
             Client.message_create := check_command
         ]}