first draft of doc comments

lib/joy.ml

@@ -34,12 +34,16 @@ let map_fill = Transform.map_fill
 let map_stroke = Transform.map_stroke
 let set_line_width = Context.set_line_width
 
+(** Initializes drawing context, takes optional arguments to set background color,
+    line width, and resolution(`size`) *)
 let init ?(background = Color.white) ?(line_width = 2) ?(size = (500, 500))
     ?(axes = false) () =
   Context.init_context (Color.opaque background)
     (float_of_int line_width)
     size axes
 
+(** Writes the current digital canvas to a PNG file, takes a filename 
+    as an optonal argument *)
 let write ?(filename = "joy.png") () =
   match !Context.context with
   | Some ctx ->

lib/render.ml

@@ -113,6 +113,7 @@ let rec render_shape ctx = function
 let render shape =
   match !context with Some ctx -> render_shape ctx shape | None -> fail ()
 
+(** Renders a list of shapes *)
 let show shapes =
   match !context with
   | Some ctx -> List.iter (render_shape ctx) shapes

lib/shape.ml

@@ -23,13 +23,15 @@ type polygon = {
   fill : color option;
 }
 
+(** Shape variant type *)
 type shape =
   | Circle of circle
   | Ellipse of ellipse
   | Line of line
   | Polygon of polygon
   | Complex of shape list
 
+(** List of shapes *)
 type shapes = shape list
 
 (* point -> point arithmetic *)
@@ -41,18 +43,22 @@ let ( /! ) { x; y } scalar = { x = x /. scalar; y = y /. scalar }
 let ( *! ) { x; y } scalar = { x = x *. scalar; y = y *. scalar }
 let pmap f { x; y } = { x = f x; y = f y }
 
+(** Point constructor function *)
 let point x y =
   let x, y = (float_of_int x, float_of_int y) in
   { x; y }
 
 let center = { x = 0.; y = 0. }
 
+(** Circle constructor function *)
 let circle ?(c = center) r =
   Circle { c; radius = float_of_int r; stroke = Some Color.black; fill = None }
 
+(** Polygon constructor function *)
 let polygon vertices =
   Polygon { vertices; stroke = Some Color.black; fill = None }
 
+(** Rectangle constructor function *)
 let rectangle ?(c = center) width height =
   let w, h = (float_of_int width, float_of_int height) in
   let x1 = c.x -. (w /. 2.) in
@@ -65,22 +71,27 @@ let rectangle ?(c = center) width height =
       { x = x1 +. w; y = y1 };
     ]
 
+(** Ellipse constructor function *)
 let ellipse ?(c = center) rx ry =
   let rx, ry = (float_of_int rx, float_of_int ry) in
   Ellipse { c; rx; ry; stroke = Some Color.black; fill = None }
 
+(** Line constructor function *)
 let line ?(a = center) b = Line { a; b; stroke = Color.black }
 
+(** Complex shape constructor function *)
 let complex shapes =
   match shapes with _ :: _ -> Complex shapes | [] -> Complex []
 
+(** Takes a color and a shape, and returns a new shape with its stroke set to that color *)
 let rec with_stroke stroke = function
   | Circle circle' -> Circle { circle' with stroke = Some stroke }
   | Ellipse ellipse' -> Ellipse { ellipse' with stroke = Some stroke }
   | Line line' -> Line { line' with stroke }
   | Polygon polygon' -> Polygon { polygon' with stroke = Some stroke }
   | Complex complex' -> Complex (List.map (with_stroke stroke) complex')
 
+(** Takes a color and a shape, and returns a new shape with its fill set to that color *)
 let rec with_fill fill = function
   | Circle circle' -> Circle { circle' with fill = Some fill }
   | Ellipse ellipse' -> Ellipse { ellipse' with fill = Some fill }

lib/transform.ml

@@ -1,7 +1,9 @@
 open Shape
 
+(** Represents a function that takes a shape, and returns that shape transformed in some way *)
 type transformation = shape -> shape
 
+(** Translation - takes an int for each axis and adds those values to the shape's position *)
 let rec translate dx dy = function
   | Circle circle ->
       let dx, dy = (float_of_int dx, float_of_int dy) in
@@ -33,6 +35,8 @@ let rec translate dx dy = function
 let scale_length fact len = len *. fact
 let pmap f { x; y } = { x = f x; y = f y }
 
+(** Multipllies a shape's size paramters (i.e. a circle's radius) 
+    by the factor argument *)
 let rec scale factor = function
   | Circle circle' ->
       Circle
@@ -73,6 +77,7 @@ let rotate_point degrees point =
   let r, theta = to_polar point in
   from_polar (r, theta +. radians)
 
+(** Rotates a shape by 0-360 degrees *)
 let rec rotate degrees = function
   | Circle circle' -> Circle { circle' with c = rotate_point degrees circle'.c }
   | Ellipse ellipse' ->
@@ -86,18 +91,22 @@ let rec rotate degrees = function
         }
   | Complex shapes -> Complex (List.map (rotate degrees) shapes)
 
+(** Composes two `transformation`s, creating a function that feeds the 
+    result of the first into the second *)
 let compose f g x = g (f x)
 let range n = List.init n Fun.id
 
+(** Iterative transformation - takes a number, an operation, and a shape and folds over `range n` feeding 
+    the result of the last transformation into the next *)
 let repeat n op shape =
   let match_list l =
     match l with [] -> [ op shape ] | last :: _ -> op last :: l
   in
   let shapes = List.fold_right (fun _ acc -> match_list acc) (range n) [] in
   complex shapes
 
-(** Takes a function and a shape and returns a new shape with the 
-    function applied to the original's color *)
+(** Takes a function and a shape, returns a new shape with the 
+    function applied to the original's `stroke` *)
 let rec map_stroke f = function
   | Circle circle' ->
       Circle { circle' with stroke = Option.map f circle'.stroke }
@@ -108,6 +117,8 @@ let rec map_stroke f = function
       Polygon { polygon' with stroke = Option.map f polygon'.stroke }
   | Complex complex' -> Complex (List.map (map_stroke f) complex')
 
+(** Takes a function and a shape, returns a new shape with the 
+    function applied to the original's `fill` *)
 let rec map_fill f = function
   | Circle circle' -> Circle { circle' with fill = Option.map f circle'.fill }
   | Ellipse ellipse' ->