From 7503db882822eca3c2385ad136f3c52e2007ca15 Mon Sep 17 00:00:00 2001
From: Adelyn Breelove <tenseiken595@gmail.com>
Date: Wed, 13 Feb 2019 10:58:17 -0700
Subject: Add docs to cache

---
 lib/cache.ml  | 46 +++++++++++++++++++++++-----------------------
 lib/cache.mli | 32 ++++++++++++++++++++------------
 lib/disml.ml  | 30 ++++++++++++++++++++++++++----
 3 files changed, 69 insertions(+), 39 deletions(-)

diff --git a/lib/cache.ml b/lib/cache.ml
index 2571b34..db1f4e2 100644
--- a/lib/cache.ml
+++ b/lib/cache.ml
@@ -5,31 +5,31 @@ module ChannelMap = Map.Make(Channel_id_t)
 module GuildMap = Map.Make(Guild_id_t)
 module UserMap = Map.Make(User_id_t)
 
-type t = {
-    text_channels: Channel_t.guild_text ChannelMap.t;
-    voice_channels: Channel_t.guild_voice ChannelMap.t;
-    categories: Channel_t.category ChannelMap.t;
-    groups: Channel_t.group ChannelMap.t;
-    private_channels: Channel_t.dm ChannelMap.t;
-    guilds: Guild_t.t GuildMap.t;
-    presences: Presence.t UserMap.t;
-    (* messages: Channel_id_t.t GuildMap.t; *)
-    unavailable_guilds: Guild_t.unavailable GuildMap.t;
-    user: User_t.t option;
-    users: User_t.t UserMap.t;
+type t =
+{ text_channels: Channel_t.guild_text ChannelMap.t
+; voice_channels: Channel_t.guild_voice ChannelMap.t
+; categories: Channel_t.category ChannelMap.t
+; groups: Channel_t.group ChannelMap.t
+; private_channels: Channel_t.dm ChannelMap.t
+; guilds: Guild_t.t GuildMap.t
+; presences: Presence.t UserMap.t
+(* ; messages: Channel_id_t.t GuildMap.t *)
+; unavailable_guilds: Guild_t.unavailable GuildMap.t
+; user: User_t.t option
+; users: User_t.t UserMap.t
 }
 
-let create () = {
-    text_channels = ChannelMap.empty;
-    voice_channels = ChannelMap.empty;
-    categories = ChannelMap.empty;
-    groups = ChannelMap.empty;
-    private_channels = ChannelMap.empty;
-    guilds = GuildMap.empty;
-    presences = UserMap.empty;
-    unavailable_guilds = GuildMap.empty;
-    user = None;
-    users = UserMap.empty;
+let create () =
+    { text_channels = ChannelMap.empty
+    ; voice_channels = ChannelMap.empty
+    ; categories = ChannelMap.empty
+    ; groups = ChannelMap.empty
+    ; private_channels = ChannelMap.empty
+    ; guilds = GuildMap.empty
+    ; presences = UserMap.empty
+    ; unavailable_guilds = GuildMap.empty
+    ; user = None
+    ; users = UserMap.empty
     }
 
 let cache =
diff --git a/lib/cache.mli b/lib/cache.mli
index 111e5bc..460afd0 100644
--- a/lib/cache.mli
+++ b/lib/cache.mli
@@ -1,26 +1,34 @@
 open Async
 open Core
 
+(** Represents a Map of {!Channel_id.t} keys. *)
 module ChannelMap : module type of Map.Make(Channel_id_t)
+
+(** Represents a Map of {!Guild_id.t} keys. *)
 module GuildMap : module type of Map.Make(Guild_id_t)
+
+(** Represents a Map of {!User_id.t} keys. *)
 module UserMap : module type of Map.Make(User_id_t)
 
-type t = {
-    text_channels: Channel_t.guild_text ChannelMap.t;
-    voice_channels: Channel_t.guild_voice ChannelMap.t;
-    categories: Channel_t.category ChannelMap.t;
-    groups: Channel_t.group ChannelMap.t;
-    private_channels: Channel_t.dm ChannelMap.t;
-    guilds: Guild_t.t GuildMap.t;
-    presences: Presence.t UserMap.t;
-    (* messages: Channel_id_t.t GuildMap.t; *)
-    unavailable_guilds: Guild_t.unavailable GuildMap.t;
-    user: User_t.t option;
-    users: User_t.t UserMap.t;
+(** The full cache record. Immutable and intended to be wrapped in a concurrency-safe wrapper such as {{!Async.Mvar.Read_write.t}Mvar}. *)
+type t =
+{ text_channels: Channel_t.guild_text ChannelMap.t
+; voice_channels: Channel_t.guild_voice ChannelMap.t
+; categories: Channel_t.category ChannelMap.t
+; groups: Channel_t.group ChannelMap.t
+; private_channels: Channel_t.dm ChannelMap.t
+; guilds: Guild_t.t GuildMap.t
+; presences: Presence.t UserMap.t
+(* ; messages: Channel_id_t.t GuildMap.t *)
+; unavailable_guilds: Guild_t.unavailable GuildMap.t
+; user: User_t.t option
+; users: User_t.t UserMap.t
 }
 
+(** A {{!t}cache} wrapped in an {{!Async.Mvar.Read_write.t}Mvar}. *)
 val cache : t Mvar.Read_write.t
 
+(** Creates a new, empty cache. *)
 val create :
     (* ?max_messages:int -> *)
     unit ->
diff --git a/lib/disml.ml b/lib/disml.ml
index 2e44658..3362bf9 100644
--- a/lib/disml.ml
+++ b/lib/disml.ml
@@ -1,5 +1,5 @@
 (**
-    {2 Dis.ml - An OCaml wrapper for the Discord API}
+    {2 Dis.ml - An OCaml library for interfacing with the Discord API}
 
     {3 Example}
 
@@ -29,13 +29,35 @@
 (** The primary interface for connecting to Discord and handling gateway events. *)
 module Client = Client
 
+(** Caching module. {!Cache.cache} is an {{!Async.Mvar.Read_write.t}Mvar}, which is always filled, containing an immutable cache record to allow for safe, concurrent access. *)
 module Cache = Cache
 
 (** Raw HTTP abstractions for Discord's REST API. *)
-module Http = Http
+module Http = struct
+    include Http
 
-(** Gateway connection and sharding manager. *)
-module Sharder = Sharder
+    (** Internal module for resolving endpoints *)
+    module Endpoints = Endpoints
+
+    (** Internal module for handling rate limiting *)
+    module Ratelimits = Rl
+end
+
+(** Gateway connection super module. *)
+module Gateway = struct
+
+    (** Internal module used for dispatching events. *)
+    module Dispatch = Dispatch
+
+    (** Internal module for representing events. *)
+    module Event = Event
+
+    (** Internal module for representing Discord's opcodes. *)
+    module Opcode = Opcode
+
+    (** Shard manager *)
+    module Sharder = Sharder
+end
 
 (** Super module for all Discord object types. *)
 module Models = struct
-- 
cgit v1.2.3