Start work on docstrings

project.clj

@@ -4,4 +4,5 @@
   :license {:name "Public Domain"
             :url "http://unlicense.org/UNLICENSE"}
   :dependencies [[com.badlogicgames.gdx/gdx "0.9.9"]
-                 [org.clojure/clojure "1.5.1"]])
+                 [org.clojure/clojure "1.5.1"]]
+  :plugins [[lein-marginalia "0.7.1"]])

src/play_clj/core.clj

@@ -26,11 +26,13 @@
 (load "core_listeners")
 
 (defn ^:private reset-changed!
+  "Internal use only"
   [e-atom e-old e-new]
   (when (not= e-old e-new)
     (compare-and-set! e-atom e-old e-new)))
 
 (defn defscreen*
+  "Internal use only"
   [{:keys [on-show on-render on-hide on-pause on-resize on-resume]
     :as options}]
   (let [screen (atom {})
@@ -68,6 +70,20 @@
      :input-listeners (global-listeners options execute-fn!)}))
 
 (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 text-screen
+      :on-show
+      (fn [screen entities]
+        (update! screen :renderer (stage))
+        (label \"Hello world!\" (color :white)))
+      :on-render
+      (fn [screen entities]
+        (clear!)
+        (render! screen entities)))
+"
   [n & {:keys [] :as options}]
   `(let [fns# (->> (for [[k# v#] ~options]
                      [k# (intern *ns* (symbol (str '~n "-" (name k#))) v#)])
@@ -76,16 +92,30 @@
      (defonce ~n (defscreen* fns#))))
 
 (defn defgame*
+  "Internal use only"
   [{:keys [on-create]}]
   (proxy [Game] []
     (create []
       (when on-create (on-create this)))))
 
 (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)))"
   [n & {:keys [] :as options}]
   `(defonce ~n (defgame* ~options)))
 
 (defn set-screen!
+  "Creates a [Screen](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/Screen.html)
+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)
+"
   [^Game game & screens]
   (let [add-inputs! (fn []
                       (input! :set-input-processor (InputMultiplexer.))
@@ -105,5 +135,10 @@
                        (dispose [this])))))
 
 (defn update!
+  "Runs the equivalent of `(swap! screen-atom assoc ...)`, where `screen-atom`
+is the atom storing the screen map behind the scenes
+
+    (update! screen :renderer (stage))
+"
   [{:keys [update-fn!]} & {:keys [] :as args}]
   (update-fn! args))

src/play_clj/g2d.clj

@@ -4,10 +4,16 @@
            [com.badlogic.gdx.graphics.g2d Animation BitmapFont TextureRegion]))
 
 (defmacro bitmap-font
+  "Returns a [BitmapFont](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/graphics/g2d/BitmapFont.html)
+
+    (bitmap-font)
+    (bitmap-font file-handle region)
+"
   [& options]
   `(BitmapFont. ~@options))
 
 (defn texture*
+  "The function version of `texture`"
   [arg]
   (u/create-entity
     (cond
@@ -19,34 +25,74 @@
       arg)))
 
 (defmacro texture
+  "Returns an entity based on [TextureRegion](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/graphics/g2d/TextureRegion.html)
+
+    (texture \"image.png\")
+    (texture \"image.png\" :flip true false)
+    (texture \"image.png\"
+             :flip true false
+             :set-region 0 0 100 100)
+"
   [arg & options]
   `(let [entity# (texture* ~arg)]
      (u/calls! ^TextureRegion (u/get-obj entity# :object) ~@options)
      entity#))
 
 (defmacro texture!
+  "Calls a single method on a `texture` entity, returning whatever the method
+itself does
+
+    (texture! entity :flip true false)
+    (texture! entity :get-region-width)
+"
   [entity k & options]
   `(u/call! ^TextureRegion (u/get-obj ~entity :object) ~k ~@options))
 
 (defmacro play-mode
+  "Returns a static field from [Animation](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/graphics/g2d/Animation.html)
+
+    (play-mode :loop)
+    (play-mode :loop-pingpong)
+    (play-mode :loop-random)
+    (play-mode :loop-reversed)
+    (play-mode :normal)
+    (play-mode :reversed)
+"
   [key]
   `(u/static-field-upper :graphics :g2d :Animation ~key))
 
 (defn animation*
+  "The function version of `animation`"
   [duration textures]
   (Animation. duration
               (u/gdx-array (map #(u/get-obj % :object) textures))
               (play-mode :normal)))
 
 (defmacro animation
+  "Returns an [Animation](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/graphics/g2d/Animation.html) object
+
+    (animation 0.2
+               [walk-1 walk-2 walk-3]
+               :set-play-mode (play-mode :loop-pingpong))
+"
   [duration textures & options]
   `(u/calls! ^Animation (animation* ~duration ~textures) ~@options))
 
 (defmacro animation!
+  "Calls a single method on an `animation` object, returning whatever the method 
+itself does
+
+    (animation! object :set-play-mode (play-mode :loop))
+"
   [object k & options]
   `(u/call! ^Animation ~object ~k ~@options))
 
 (defn animation->texture
+  "Returns a `texture` entity with a frame from `animation` based on the total
+time the `screen` has been showing
+
+    (animation->texture screen anim)
+"
   ([{:keys [total-time]} ^Animation animation]
     (texture* (.getKeyFrame animation total-time true)))
   ([{:keys [total-time]} ^Animation animation is-looping?]