More signature improvements

5 files changed, 70 insertions, 11 deletions

diff --git a/lib/client.mli b/lib/client.mli
index 6f6a18d..333715f 100644
--- a/lib/client.mli
+++ b/lib/client.mli
@@ -3,15 +3,36 @@ open Async
 include module type of Client_options
 include module type of Dispatch
 
+(** Type of the Client, it isn't recommended to access the fields directly. *)
 type t = {
     sharder: Sharder.t;
     token: string;
 }
 
+(** Start the Client. This begins shard connections to Discord and event handlers should be registered prior to calling this.
+    {3 Example}
+    {[
+        open Async
+        open Disml
+
+        let main () =
+            let token = "a valid bot token" in
+            Client.start ~count:5 token >>> print_endline "Client launched"
+
+        let _ =
+            Scheduler.go_main ~main ()
+    ]}
+    @param ?count Optional amount of shards to launch. Defaults to autosharding
+    @param string The token used for authentication
+    @return A deferred client object
+*)
 val start : ?count:int -> string -> t Deferred.t
 
+(** Same as {!Sharder.set_status} where [client.sharder] is passed. *)
 val set_status : status:Yojson.Safe.json -> t -> Sharder.Shard.shard list Deferred.t
 
+(** Same as {!Sharder.set_status_with} where [client.sharder] is passed. *)
 val set_status_with : f:(Sharder.Shard.shard -> Yojson.Safe.json) -> t -> Sharder.Shard.shard list Deferred.t
 
+(** Same as {!Sharder.request_guild_members} where [client.sharder] is passed. *)
 val request_guild_members : guild:Snowflake.t -> ?query:string -> ?limit:int -> t -> Sharder.Shard.shard list Deferred.t
\ No newline at end of file
diff --git a/lib/endpoints.mli b/lib/endpoints.mli
index aba0eb7..2abe01d 100644
--- a/lib/endpoints.mli
+++ b/lib/endpoints.mli
@@ -1,3 +1,5 @@
+(** Endpoint formatters used internally. *)
+
 val gateway : string
 val gateway_bot : string
 val channel : int -> string
diff --git a/lib/event.mli b/lib/event.mli
index 8f0ab5f..0c5aba1 100644
--- a/lib/event.mli
+++ b/lib/event.mli
@@ -1,5 +1,9 @@
+(** Barebones of event dispatching. Most users will have no reason to look here. *)
+
+(** Used internally when received an unknown event. Is caught and logged. *)
 exception Invalid_event of string
 
+(** Event dispatch type wrapper. Used internally. *)
 type t =
 | HELLO of Yojson.Safe.json
 | READY of Yojson.Safe.json
@@ -37,8 +41,11 @@ type t =
 | VOICE_SERVER_UPDATE of Yojson.Safe.json
 | WEBHOOKS_UPDATE of Yojson.Safe.json
 
+(** Used to convert an event string and payload into a t wrapper type. *)
 val event_of_yojson : contents:Yojson.Safe.json -> string -> t
 
+(** Sends the event to the registered handler. *)
 val dispatch : t -> unit
 
+(** Wrapper to other functions. This is called from the shards. *)
 val handle_event : ev:string -> Yojson.Safe.json -> unit
\ No newline at end of file
diff --git a/lib/opcode.mli b/lib/opcode.mli
index e07f82e..b0e7adb 100644
--- a/lib/opcode.mli
+++ b/lib/opcode.mli
@@ -1,18 +1,29 @@
+(** Internal Opcode abstractions. *)
+
+(** Type of known opcodes. *)
 type t =
-    | DISPATCH
-    | HEARTBEAT
-    | IDENTIFY
-    | STATUS_UPDATE
-    | VOICE_STATE_UPDATE
-    | RESUME
-    | RECONNECT
-    | REQUEST_GUILD_MEMBERS
-    | INVALID_SESSION
-    | HELLO
-    | HEARTBEAT_ACK
+| DISPATCH
+| HEARTBEAT
+| IDENTIFY
+| STATUS_UPDATE
+| VOICE_STATE_UPDATE
+| RESUME
+| RECONNECT
+| REQUEST_GUILD_MEMBERS
+| INVALID_SESSION
+| HELLO
+| HEARTBEAT_ACK
 
+(** Raised when receiving an invalid opcode. This should never occur. *)
 exception Invalid_Opcode of int
 
+(** Converts an opcode to its integer form for outgoing frames. *)
 val to_int : t -> int
+
+(** Converts an integer to an opcode for incoming frames.
+    Raise {!Invalid_Opcode} Raised when an unkown opcode is received.
+*)
 val from_int : int -> t
+
+(** Converts and opcode to a human-readable string. Used for logging purposes. *)
 val to_string : t -> string
\ No newline at end of file
diff --git a/lib/rl.mli b/lib/rl.mli
index f583653..973f02f 100644
--- a/lib/rl.mli
+++ b/lib/rl.mli
@@ -1,19 +1,37 @@
+(** Internal ratelimit route mapping. *)
+
 open Core
 open Async
 
+(** Type for mapping route -> {!rl}. *)
 module RouteMap : module type of Map.Make(String)
 
+(** Type representing ratelimit information. *)
 type rl = {
     limit: int;
     remaining: int;
     reset: int;
 }
 
+(** Type representing the specific case of {!RouteMap}. *)
 type t = ((rl, read_write) Mvar.t) RouteMap.t
 
+(** Converts Cohttp header data into ratelimit information.
+    @return Some of ratelimit information or None on bad headers
+*)
 val rl_of_header : Cohttp.Header.t -> rl option
+
+(** Default for type rl. Used for prepopulating routes. *)
 val default : rl
+
+(** Empty ratelimit route map. *)
 val empty : t
+
+(** Analogous to {!RouteMap.update}. *)
 val update : 'a RouteMap.t -> string -> f:('a option -> 'a) -> 'a RouteMap.t
+
+(** Analogous to {!RouteMap.find}. *)
 val find : 'a RouteMap.t -> string -> 'a option
+
+(** Analogous to {!RouteMap.find_exn}. *)
 val find_exn : 'a RouteMap.t -> string -> 'a
\ No newline at end of file