Add docstrings to core-graphics

src/play_clj/core.clj

@@ -72,18 +72,7 @@
 (defmacro defscreen
   "Creates vars for all the anonymous functions provided to it, so they can be
 replaced by simply reloading the namespace, and creates a var for the symbol `n`
-bound to a map containing various important values related to the screen
-
-    (defscreen main-screen
-      :on-show
-      (fn [screen entities]
-        (update! screen :renderer (stage))
-        (label \"Hello world!\" (color :white)))
-      :on-render
-      (fn [screen entities]
-        (clear!)
-        (render! screen entities)))
-"
+bound to a map containing various important values related to the screen"
   [n & {:keys [] :as options}]
   `(let [fns# (->> (for [[k# v#] ~options]
                      [k# (intern *ns* (symbol (str '~n "-" (name k#))) v#)])
@@ -100,12 +89,7 @@ bound to a map containing various important values related to the screen
 
 (defmacro defgame
   "Creates a var for the symbol `n` bound to a [Game](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/Game.html)
-object
-
-    (defgame hello-world
-      :on-create
-      (fn [this]
-        (set-screen! this main-screen)))"
+object"
   [n & {:keys [] :as options}]
   `(defonce ~n (defgame* ~options)))
 
@@ -114,7 +98,7 @@ object
 object, sets it as the screen for the `game`, and runs the functions from
 `screens` in the order they are provided in
 
-    (set-screen! hello-world main-screen)
+    (set-screen! hello-world main-screen text-screen)
 "
   [^Game game & screens]
   (let [add-inputs! (fn []

src/play_clj/core_global.clj

@@ -17,7 +17,10 @@
 
 (defmacro color
   "Returns a [Color](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/graphics/Color.html)
-object"
+
+    (color :white)
+    (color 1 1 1 1)
+"
   [& args]
   `~(if (keyword? (first args))
       `(Color. ^Color (u/static-field-upper :graphics :Color ~(first args)))

src/play_clj/core_graphics.clj

@@ -3,21 +3,35 @@
 ; tiled maps
 
 (defn tiled-map*
+  "The function version of `tiled-map`"
   [s]
   (if (string? s)
     (.load (TmxMapLoader.) s)
     s))
 
 (defmacro tiled-map
+  "Returns a [TiledMap](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/tiled/TiledMap.html)
+
+    (tiled-map \"level1.tmx\")
+"
   [s & options]
   `(u/calls! ^TiledMap (tiled-map* ~s) ~@options))
 
 (defmacro tiled-map!
+  "Calls a single method on a `tiled-map`
+
+    (tiled-map! screen :get-layers)
+"
   [screen k & options]
   `(let [^BatchTiledMapRenderer object# (u/get-obj ~screen :renderer)]
      (u/call! ^TiledMap (.getMap object#) ~k ~@options)))
 
 (defn tiled-map-layers
+  "Returns a list with [MapLayer](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/MapLayer.html)
+objects cooresponding to each layer in the tiled map in `screen`
+
+    (tiled-map-layers screen)
+"
   [screen]
   (let [^BatchTiledMapRenderer renderer (u/get-obj screen :renderer)
         ^MapLayers layers (-> renderer .getMap .getLayers)]
@@ -25,6 +39,7 @@
       (.get layers i))))
 
 (defn tiled-map-layer*
+  "The function version of `tiled-map-layer`"
   [screen layer]
   (if (isa? (type layer) MapLayer)
     layer
@@ -33,104 +48,161 @@
          first)))
 
 (defmacro tiled-map-layer
+  "Returns a [TiledMapTileLayer](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/tiled/TiledMapTileLayer.html)
+from the tiled map in `screen` that matches `layer`
+
+    (tiled-map-layer screen \"water\")
+"
   [screen layer & options]
   `(let [^TiledMapTileLayer object# (tiled-map-layer* ~screen ~layer)]
      (u/calls! object# ~@options)))
 
 (defmacro tiled-map-layer!
+  "Calls a single method on a `tiled-map-layer`
+
+    (tiled-map-layer! (tiled-map-layer screen \"water\")
+                      :set-cell 0 0 nil)
+"
   [object k & options]
   `(u/call! ^TiledMapTileLayer (cast TiledMapTileLayer ~object) ~k ~@options))
 
 (defn tiled-map-cell*
+  "The function version of `tiled-map-cell`"
   [screen layer x y]
   (.getCell ^TiledMapTileLayer (tiled-map-layer screen layer) x y))
 
 (defmacro tiled-map-cell
+  "Returns a [TiledMapTileLayer.Cell](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/tiled/TiledMapTileLayer.Cell.html)
+from the tiled map in `screen` from the given `layer` and position `x` and `y`
+
+    (tiled-map-cell screen \"water\" 0 0)
+"
   [screen layer x y & options]
   `(let [^TiledMapTileLayer$Cell object# (tiled-map-cell* ~screen ~layer ~x ~y)]
      (u/calls! object# ~@options)))
 
 (defmacro tiled-map-cell!
+  "Calls a single method on a `tiled-map-cell`
+
+    (tiled-map-cell! (tiled-map-cell screen \"water\" 0 0)
+                     :set-rotation 90)
+"
   [object k & options]
   `(u/call! ^TiledMapTileLayer$Cell ~object ~k ~@options))
 
 ; renderers
 
 (defn orthogonal-tiled-map*
+  "The function version of `orthogonal-tiled-map`"
   [path unit]
   (OrthogonalTiledMapRenderer. ^TiledMap (tiled-map* path) ^double unit))
 
 (defmacro orthogonal-tiled-map
+  "Returns an [OrthogonalTiledMapRenderer](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/tiled/renderers/OrthogonalTiledMapRenderer.html)
+with the tiled map file at `path` and `unit` scale
+
+    (orthogonal-tiled-map \"level1.tmx\" (/ 1 8))
+"
   [path unit & options]
   `(u/calls! ^OrthogonalTiledMapRenderer (orthogonal-tiled-map* ~path ~unit)
              ~@options))
 
 (defmacro orthogonal-tiled-map!
+  "Calls a single method on an `orthogonal-tiled-map`"
   [screen k & options]
   `(let [^OrthogonalTiledMapRenderer object# (u/get-obj ~screen :renderer)]
      (u/call! object# ~k ~@options)))
 
 (defn isometric-tiled-map*
+  "The function version of `isometric-tiled-map`"
   [path unit]
   (IsometricTiledMapRenderer. ^TiledMap (tiled-map* path) ^double unit))
 
 (defmacro isometric-tiled-map
+  "Returns an [IsometricTiledMapRenderer](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/tiled/renderers/IsometricTiledMapRenderer.html)
+with the tiled map file at `path` and `unit` scale
+
+    (isometric-tiled-map \"level1.tmx\" (/ 1 8))
+"
   [path unit & options]
   `(u/calls! ^IsometricTiledMapRenderer (isometric-tiled-map* ~path ~unit)
              ~@options))
 
 (defmacro isometric-tiled-map!
+  "Calls a single method on an `isometric-tiled-map`"
   [screen k & options]
   `(let [^IsometricTiledMapRenderer object# (u/get-obj ~screen :renderer)]
      (u/call! object# ~k ~@options)))
 
 (defn isometric-staggered-tiled-map*
+  "The function version of `isometric-staggered-tiled-map`"
   [path unit]
   (IsometricStaggeredTiledMapRenderer. ^TiledMap (tiled-map* path)
                                        ^double unit))
 
 (defmacro isometric-staggered-tiled-map
+  "Returns an [IsometricStaggeredTiledMapRenderer](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/tiled/renderers/IsometricStaggeredTiledMapRenderer.html)
+with the tiled map file at `path` and `unit` scale
+
+    (isometric-staggered-tiled-map \"level1.tmx\" (/ 1 8))
+"
   [path unit & options]
   `(u/calls! ^IsometricStaggeredTiledMapRenderer
              (isometric-staggered-tiled-map* ~path ~unit)
              ~@options))
 
 (defmacro isometric-staggered-tiled-map!
+  "Calls a single method on an `isometric-staggered-tiled-map`"
   [screen k & options]
   `(let [^IsometricStaggeredTiledMapRenderer object#
          (u/get-obj ~screen :renderer)]
      (u/call! object# ~k ~@options)))
 
 (defn hexagonal-tiled-map*
+  "The function version of `hexagonal-tiled-map`"
   [path unit]
   (HexagonalTiledMapRenderer. ^TiledMap (tiled-map* path) ^double unit))
 
 (defmacro hexagonal-tiled-map
+  "Returns a [HexagonalTiledMapRenderer](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/tiled/renderers/HexagonalTiledMapRenderer.html)
+with the tiled map file at `path` and `unit` scale
+
+    (hexagonal-tiled-map \"level1.tmx\" (/ 1 8))
+"
   [path unit & options]
   `(u/calls! ^HexagonalTiledMapRenderer (hexagonal-tiled-map* ~path ~unit)
              ~@options))
 
 (defmacro hexagonal-tiled-map!
+  "Calls a single method on a `hexagonal-tiled-map`"
   [screen k & options]
   `(let [^HexagonalTiledMapRenderer object# (u/get-obj ~screen :renderer)]
      (u/call! object# ~k ~@options)))
 
 (defn stage*
+  "The function version of `stage`"
   []
   (Stage.))
 
 (defmacro stage
+  "Returns a [Stage](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/scenes/scene2d/Stage.html)
+
+    (stage)
+"
   [& options]
   `(u/calls! ^Stage (stage*) ~@options))
 
 (defmacro stage!
+  "Calls a single method on a `stage`"
   [screen k & options]
   `(let [^Stage object# (u/get-obj ~screen :renderer)]
      (u/call! object# ~k ~@options)))
 
 ; batch
 
-(defmulti batch #(-> % :renderer class))
+(defmulti batch
+  "Internal use only"
+  #(-> % :renderer class))
 
 (defmethod batch BatchTiledMapRenderer
   [{:keys [^BatchTiledMapRenderer renderer]}]
@@ -142,7 +214,9 @@
 
 ; rendering
 
-(defmulti draw-entity! (fn [_ entity] (:type entity)))
+(defmulti draw-entity!
+  "Internal use only"
+  (fn [_ entity] (:type entity)))
 
 (defmethod draw-entity! nil [_ _])
 
@@ -167,7 +241,12 @@
         height (float (or height (.getRegionHeight object)))]
     (.draw batch object x y width height)))
 
-(defn draw! [{:keys [renderer] :as screen} entities]
+(defn draw!
+  "Draws the `entities` with the renderer from `screen`
+
+    (draw! screen entities)
+"
+  [{:keys [renderer] :as screen} entities]
   (assert renderer)
   (let [^SpriteBatch batch (batch screen)]
     (.begin batch)
@@ -177,11 +256,13 @@
   entities)
 
 (defn ^:private render-map!
+  "Internal use only"
   [{:keys [^BatchTiledMapRenderer renderer ^Camera camera]}]
   (when camera (.setView renderer camera))
   (.render renderer))
 
 (defn ^:private render-stage!
+  "Internal use only"
   [{:keys [^Stage renderer ^Camera camera]}]
   (when camera
     (.setCamera renderer camera)
@@ -189,6 +270,11 @@
   (doto renderer .act .draw))
 
 (defn render!
+  "Calls the renderer from `screen` and optionally draws and returns the
+`entities`
+
+    (render! screen entities)
+"
   ([{:keys [renderer] :as screen}]
     (cond
       (isa? (type renderer) BatchTiledMapRenderer)
@@ -202,48 +288,75 @@
 ; cameras
 
 (defn orthographic*
+  "The function version of `orthographic`"
   []
   (OrthographicCamera.))
 
 (defmacro orthographic
+  "Returns an [OrthographicCamera](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/graphics/OrthographicCamera.html)
+
+    (orthographic)
+"
   [& options]
   `(let [^OrthographicCamera object# (orthographic*)]
      (u/calls! object# ~@options)))
 
 (defmacro orthographic!
+  "Calls a single method on an `orthographic`"
   [screen k & options]
   `(let [^OrthographicCamera object# (u/get-obj ~screen :camera)]
      (u/call! object# ~k ~@options)))
 
-(defn perspective
+(defn perspective*
+  "The function version of `perspective`"
   []
   (PerspectiveCamera.))
 
 (defmacro perspective
+  "Returns an [PerspectiveCamera](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/graphics/PerspectiveCamera.html)
+
+    (perspective)
+"
   [& options]
   `(let [^PerspectiveCamera object# (perspective*)]
      (u/calls! object# ~@options)))
 
 (defmacro perspective!
+  "Calls a single method on a `perspective`"
   [screen k & options]
   `(let [^PerspectiveCamera object# (u/get-obj ~screen :camera)]
      (u/call! object# ~k ~@options)))
 
 (defn size!
+  "Sets the size of the camera in `screen`
+
+    (size! screen 480 360)
+"
   [screen width height]
   (let [^OrthographicCamera camera (u/get-obj screen :camera)]
     (assert camera)
     (.setToOrtho camera false width height)))
 
-(defn height!
-  [screen new-height]
-  (size! screen (* new-height (/ (game :width) (game :height))) new-height))
-
 (defn width!
+  "Sets the width of the camera in `screen`, adjusting the height so the ratio
+remains in tact
+
+    (width! screen 480)
+"
   [screen new-width]
   (size! screen new-width (* new-width (/ (game :height) (game :width)))))
 
+(defn height!
+  "Sets the height of the camera in `screen`, adjusting the width so the ratio
+remains in tact
+
+    (height! screen 360)
+"
+  [screen new-height]
+  (size! screen (* new-height (/ (game :width) (game :height))) new-height))
+
 (defn x!
+  "Sets only the x position of the camera in `screen`"
   [screen x]
   (let [^Camera camera (u/get-obj screen :camera)]
     (assert camera)
@@ -251,6 +364,7 @@
     (.update camera)))
 
 (defn y!
+  "Sets only the y position of the camera in `screen`"
   [screen y]
   (let [^Camera camera (u/get-obj screen :camera)]
     (assert camera)
@@ -258,6 +372,7 @@
     (.update camera)))
 
 (defn z!
+  "Sets only the z position of the camera in `screen`"
   [screen z]
   (let [^Camera camera (u/get-obj screen :camera)]
     (assert camera)
@@ -265,6 +380,7 @@
     (.update camera)))
 
 (defn position!
+  "Sets the position of the camera in `screen`"
   ([screen x y]
     (position! screen x y nil))
   ([screen x y z]

src/play_clj/g2d.clj

@@ -39,8 +39,7 @@
      entity#))
 
 (defmacro texture!
-  "Calls a single method on a `texture` entity, returning whatever the method
-itself does
+  "Calls a single method on a `texture`
 
     (texture! entity :flip true false)
     (texture! entity :get-region-width)
@@ -69,7 +68,7 @@ itself does
               (play-mode :normal)))
 
 (defmacro animation
-  "Returns an [Animation](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/graphics/g2d/Animation.html) object
+  "Returns an [Animation](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/graphics/g2d/Animation.html)
 
     (animation 0.2
                [walk-1 walk-2 walk-3]
@@ -79,8 +78,7 @@ itself does
   `(u/calls! ^Animation (animation* ~duration ~textures) ~@options))
 
 (defmacro animation!
-  "Calls a single method on an `animation` object, returning whatever the method 
-itself does
+  "Calls a single method on an `animation`
 
     (animation! object :set-play-mode (play-mode :loop))
 "