mli spec + some extra specs

command.mli

@@ -22,4 +22,8 @@ type command =
 exception Empty
 exception Malformed
 
+(**[parse string] is the command type which a player wants to be acted upon. 
+   It takes in a string and converts it to a type of command.
+   Raises: Empty if no command given or just whitespace;
+           Malformed if not a recognized command;*)
 val parse: string -> command

marketmaker.ml

@@ -204,6 +204,7 @@ let stringify_bid_ask (market : t) =
   (string_of_int market.currbidask.bid) ^ "@" ^ 
   (string_of_int market.currbidask.ask)
 
+(**[get_timestamp market] is the value of the timestamp in the market  *)
 let get_timestamp (market : t) = 
   market.timestamp
 

marketmaker.mli

@@ -42,14 +42,56 @@ type receive_transaction =  {
   transaction : bidask;
 }
 
+(**[init_market game] is the initial state of the market after a [game] is 
+   started. It initializes all fields to its starting values and marks
+   the "trade_type" field in the record as "init".  *)
 val init_market : string -> t
+
+(**[get_timestamp market] is the value of the timestamp in the market  *)
 val get_timestamp : t -> int
+
+(**[transaction market trade] is the new state of the marketmaker after a trade.
+   It takes in a type t [market] and a [trade] and sets a new inventory, 
+   bidask, timestamp, orderbook and curr_profit for the marketmaker.
+   We update the timestamp here.
+*)
 val transaction : receive_transaction -> t -> t
+
+(**[generate_receive_transaction timestamp trade_type bid ask] returns a 
+   transaction variant with the given arguments. *)
 val generate_receive_transaction : int -> string -> int -> int -> 
   receive_transaction
+
+(**[stringify_bid_ask market] is a string of the current bid and ask. *)
 val stringify_bid_ask : t -> string
+
+(**  [get_outstandingshares market] returns the outstanding shares of the 
+     market maker's state [market]. *)
 val get_outstandingshares : t -> int
+
+(**[increment_timestep market] is a type t [market] with the timestamp 
+   incremented. *)
 val increment_timestep : t -> t
+
+(**[display_data state] is a unit with side-effects of displaying data about 
+   transactions and the currents status of the player and market. 
+
+   This uses ANSITerminal to pretty-print the market maker's statistics.
+   It currently includes the following data:
+   - Current Bid/Ask
+   - Spread
+   - Timestamp
+   - Current Profit
+   - # Coins accumulated
+*)
 val display_data : t -> unit
+
+(**  [stringify_bidask_history market] returns a history of past market markets
+     as seen in [market] state.  *)
 val stringify_bidask_history : t -> unit
+
+(** [exchange_mm_excess market sum_dice] will return a new market.t object 
+    with excess/deficient shares of camlcoin swapped for cash in accordance 
+    with the true market value, [sum_dice].  The final excess coins will be 0 
+    (invariant).  *)
 val exchange_mm_excess : t -> int -> t

parse.mli

@@ -16,11 +16,29 @@ val fermi_json : t
 val oth_situation : situation
 val first_situation : situation
 (* END *)
+
+(**[from_json json] is a type t with values from the [json] file. *)
 val from_json : Yojson.Basic.t -> t
+
+(** [get_question data] returns a question from the [data] variant *)
 val get_question : t -> string
+
+(** [get_answer data] returns an answer from the [data] variant *)
 val get_answer : t -> string
+
+(* [get_nth_situation index data] is the nth situation from json. *)
 val get_nth_situation : int -> t -> situation
+
+(* [get_event_from_situation sit] is the event from a situation.  *)
 val get_event_from_situation: situation -> string
+
+(* [get_effect_from_situation sit] is the effect from a situation. It's an 
+   option indicating if it it causes the price to rise or to fall *)
 val get_effect_from_situation : situation -> (string * string) option
+
+(**[get_intro data] results in the ascii introduction string being printed from 
+   the json. *)
 val get_intro : t -> unit
+
+(** [show_dice n] returns a string indicating a dice with visible face [n]. *)
 val show_dice : int -> string

stats.ml

@@ -36,8 +36,11 @@ let rec roll_list (num:int) (acc: int list) : (int list) =
   else 
     roll_list (num - 1) ((1 + Random.int 5)::acc)
 
+(**[get_player_roll d] gives the number the player rolled *)
 let get_player_roll (d:dice_data) : int = d.player_roll
 
+(**[mega_roll num_opp] gives dice data based on how many traders the player 
+    is going against  *)
 let mega_roll (num_opp:int) : dice_data =
   let playroll = (Random.int 5) + 1 in 
   let other_list = roll_list num_opp [] in
@@ -171,6 +174,7 @@ let rec ask_acc (lst : Marketmaker.bidask list) acc =
   | [] -> List.rev acc
   | h::t -> ask_acc t (h.ask::acc)
 
+(**[text_capture market] prints out "Trace" when called  *)
 let text_capture (market : Marketmaker.t) =
   print_endline "Trace";
   ()

stats.mli

@@ -19,13 +19,38 @@ type dice_data = {
   sum_rolls : int;
 }
 
+(**[mega_roll num_opp] gives dice data based on how many traders the player 
+    is going against  *)
 val mega_roll : int -> dice_data
+
+(**[get_player_roll d] gives the number the player rolled *)
 val get_player_roll : dice_data -> int
+(**[to_float_list lst] is a list of floats converted from the string list 
+   [lst] *)
 val to_float_list : string list -> float list
+
+(**[get_mean] is the mean of the values in lst. *)
 val get_mean : float list -> float
+
+(**[get_variance lst] is the variance of the values in [lst]. *)
 val get_variance : float list -> float
+
+(**[last_three_lsr lst] is the prediction of the next values based on the least 
+   squares of the last three values in [lst].*)
 val last_three_lsr : int list -> float
+
+(**[get_graph market trader] is a record of the bids and asks put by the player, 
+   the types of trades made and the true value of the security. It takes in 
+   a [market] type t and a [trader] type t*)
 val get_graph : Marketmaker.t -> Trader.t -> graph_data 
+
+(**[text_capture market] prints out "Trace" when called  *)
 val text_capture : Marketmaker.t -> unit
+
+(**[linear_reg_cheat market] is the linear regression of the bids or asks in 
+   the market based on what the market has seen more of.  *)
 val linear_reg_cheat : Marketmaker.t -> dice_data -> float
+
+(**[chebyshev_like_var var] Uses the normal variance of a float list, and
+    calculates chebyshevs variance  *)
 val chebyshev_like_var : float -> float

trader.mli

@@ -48,9 +48,49 @@ type trader_players = {
   ai2 : t;
 }
 
-
+(**[init_trader hidden identifier] initalizes a trader record with hidden number 
+   [hidden] and id equal to [identifier] *)
 val init_trader :  int -> string -> t
+
+(**[make_trade trader transaction] is an option either of Some new type t trader 
+   (or the old trader depending on whether the trader will accept the 
+   marketmaker's bid for the security) or None which indicates whether trade 
+   was accepted.
+
+   AI Description:
+   This is one AI choice where the trader will trade according to the trader's 
+   current positions.  We describe the trader to be "flaky" as the trader does
+   not want to hold excess shares, but still wants to participate in trades. 
+   The trader will sell shares after accumulating a certain amount and will
+   buy shares if deficient.   In addition, the trader will purchase shares if
+   the current offer is less than the average holding.
+
+   This AI is meant to mimic a trader with small starting capital.
+*)
 val make_trade : t -> transaction -> (t * string) option
+
+(** [make_trade_dumb trader transaction] is an option either of Some new type 
+    t trader (or the old trader depending on whether the trader will accept the 
+    marketmaker's bid for the security) or None which indicates whether trade 
+    was accepted.
+
+    AI Description:
+    [make_trader_dumb] is described as "dumb" because the trader does not keep
+    track of its holdings.  It looks at its hidden number and calculates the
+    expected value of the sum of all remaining dice. It then transacts according
+    to this calculated expected value, without keeping track of its holdings.
+
+    This is meant to simulate a perfect trader who only trades according to EV.
+*)
 val make_trade_dumb : t -> transaction -> (t * string) option
+
+(**[make_transaction timestamp bid ask order_type] returns a variant transaction
+   that takes in a [timestamp], [order_type] and a [bid] and [ask]. *)
 val make_transaction : int -> int -> int -> string -> transaction
+
+(** [contention_for_trade traders_data trans] will return an option indicating a 
+    single transaction, indicating the outcome for the market maker's bid/ask. 
+    It randomly choses a trader from all traders who are willing to transact.
+    If no traders want to transact, it returns None. 
+*)
 val contention_for_trade: trader_players -> transaction -> (t * string) option