   (-> v nil-indexes shuffle first))
 
 ;; Then, we associate the index with a new tile in the board representation. A
-;; function that builds the tile must be provided because the details about what
-;; a tile looks like aren't really important and somebody else should take care 
-;; of them.
+;; function that builds the tile must be provided because we don't really care
+;; about its details.
 
 (defn add-tile
-  "Takes a board and returns a new one with one more tile, where tile-fn is a
-   function that returns a new tile."
+  "Takes a board and returns a new one with one empty square replaced by the
+   return value of tile-fn."
   [tile-fn board]
   (assoc board (rand-nil-index board) (tile-fn)))
 

      (d/div {:className "end-message"}
        (if (won? board) "You win!" "You lose!")))))

;; A target DOM element also needs to be specified when rendering a Quiescent
;; component. Because we'll need to perform two renders per move (one for each
;; animation phase) it's convenient to hide such details in a render function.

(defn render
  "Renders the Game component to the DOM node with the 'game' id with the given

;; As you can probably guess, our board representation needs to be transformed
;; into something that SquareBoard (defined in section 'Rendering') can make
;; sense of. Additionaly, the transformation must remove the novelty when the
;; slide phase is rendered. The next steps illustrate a way to achieve that.
;; - Keep only the tiles of the board by removing the empty squares and
;;   associate on each one :pos to a vector with the column and the row of the
;;   square the it is located.
;; - If no novelty must be present, remove new tiles and replace synthesized
;;   tiles with the original ones. Those tiles will have the position of their
;;   synthesis because during the animation they need to slide there before
;;   being merged.
;; - Associate :classes with "fade-in" on the tiles containing the :new key to
;;   animate its appearence by scaling them to its actual size from an almost
;;   invisible dimension. For the first turn there will be exactly two new
;;   tiles. For the others there will be always one.
;; - Associate :classes with "highlight" on tiles containing the :src key to
;;   animate its appearence by scaling them to a size a little bigger and then
;;   back to its original dimension. The board does not necessarily have to
;;   contain any synthesized tiles.
;; - Sort the tiles by their :key to ensure React doesn't remove and insert any
;;   DOM elements breaking the CSS transition as discussed in the 'Rendering'
;;   section.

(defn board->tiles
  "Returns a sequence of tiles taken from board with their :pos and sorted by
