Add docstrings to g2d-physics

src/play_clj/core_graphics.clj

@@ -11,9 +11,8 @@
 
 (defmacro tiled-map
   "Returns a [TiledMap](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/maps/tiled/TiledMap.html)
-
+(normally, you don't need to use this directly, because the *-tiled-map
-    (tiled-map \"level1.tmx\")
+macros that create the renderers will call this themselves)"
-"
   [s & options]
   `(u/calls! ^TiledMap (tiled-map* ~s) ~@options))
 

src/play_clj/core_listeners.clj

@@ -3,6 +3,7 @@
 ; global
 
 (defn ^:private input-processor
+  "Internal use only"
   [{:keys [on-key-down on-key-typed on-key-up on-mouse-moved
            on-scrolled on-touch-down on-touch-dragged on-touch-up]}
    execute-fn!]
@@ -63,10 +64,12 @@
       false)))
 
 (defn ^:private gesture-detector
+  "Internal use only"
   [options execute-fn!]
   (proxy [GestureDetector] [(gesture-listener options execute-fn!)]))
 
 (defn ^:private global-listeners
+  "Internal use only"
   [options execute-fn!]
   [(input-processor options execute-fn!)
    (gesture-detector options execute-fn!)])
@@ -74,6 +77,7 @@
 ; ui
 
 (defn ^:private actor-gesture-listener
+  "Internal use only"
   [{:keys [on-ui-fling on-ui-long-press on-ui-pan on-ui-pinch
            on-ui-tap on-ui-touch-down on-ui-touch-up on-ui-zoom]}
    execute-fn!]
@@ -100,12 +104,14 @@
       (execute-fn! on-ui-zoom :event e :initial-distance id :distance d))))
 
 (defn ^:private change-listener
+  "Internal use only"
   [{:keys [on-ui-changed]} execute-fn!]
   (proxy [ChangeListener] []
     (changed [e a]
       (execute-fn! on-ui-changed :event e :actor a))))
 
 (defn ^:private click-listener
+  "Internal use only"
   [{:keys [on-ui-clicked on-ui-enter on-ui-exit
            on-ui-touch-down on-ui-touch-dragged on-ui-touch-up]}
    execute-fn!]
@@ -125,6 +131,7 @@
       (execute-fn! on-ui-touch-up :event e :x x :y y :pointer p :button b))))
 
 (defn ^:private drag-listener
+  "Internal use only"
   [{:keys [on-ui-drag on-ui-drag-start on-ui-drag-stop
            on-ui-touch-down on-ui-touch-dragged on-ui-touch-up]}
    execute-fn!]
@@ -144,6 +151,7 @@
       (execute-fn! on-ui-drag-stop :event e :x x :y y :pointer p))))
 
 (defn ^:private focus-listener
+  "Internal use only"
   [{:keys [on-ui-keyboard-focus-changed on-ui-scroll-focus-changed]}
    execute-fn!]
   (proxy [FocusListener] []
@@ -153,6 +161,7 @@
       (execute-fn! on-ui-scroll-focus-changed :event e :actor a :focused? f))))
 
 (defn ^:private ui-listeners
+  "Internal use only"
   [options execute-fn!]
   [(actor-gesture-listener options execute-fn!)
    (change-listener options execute-fn!)
@@ -163,6 +172,7 @@
 ; g2d-physics
 
 (defn ^:private contact-listener
+  "Internal use only"
   [{:keys [on-begin-contact on-end-contact on-post-solve on-pre-solve]} execute-fn!]
   (reify ContactListener
     (beginContact [this c]
@@ -177,6 +187,7 @@
 ; update functions
 
 (defn ^:private update-stage!
+  "Internal use only"
   [{:keys [^Stage renderer ui-listeners]} entities]
   (doseq [^Actor a (.getActors renderer)]
     (.remove a))
@@ -189,6 +200,7 @@
   (add-input! renderer))
 
 (defn ^:private update-box-2d!
+  "Internal use only"
   [{:keys [^World world]} entities]
   (when-not (.isLocked world)
     (let [arr (u/gdx-array [])]
@@ -205,6 +217,7 @@
           (.destroyJoint world joint))))))
 
 (defn ^:private update-screen!
+  "Internal use only"
   ([{:keys [world g2dp-listener]}]
     (when (isa? (type world) World)
       (.setContactListener ^World world g2dp-listener)))

src/play_clj/g2d_physics.clj

@@ -8,6 +8,7 @@
 ; world
 
 (defn box-2d*
+  "The function version of `box-2d`"
   ([]
     (box-2d* 0 0 true))
   ([gravity-x gravity-y]
@@ -16,11 +17,16 @@
     (World. (m/vector-2 gravity-x gravity-y) sleep?)))
 
 (defmacro box-2d
+  "Returns a [World](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/physics/box2d/World.html)
+
+    (box-2d 0 0)
+"
   [gravity-x gravity-y & options]
   `(let [^World object# (box-2d* ~gravity-x ~gravity-y)]
      (u/calls! object# ~@options)))
 
 (defmacro box-2d!
+  "Calls a single method on a `box-2d`"
   [screen k & options]
   `(let [^World object# (u/get-obj ~screen :world)]
      (u/call! object# ~k ~@options)))
@@ -28,80 +34,103 @@
 ; bodies
 
 (defmacro ^:private body-type
+  "Internal use only"
   [k]
   `(symbol (str u/main-package ".physics.box2d.BodyDef$BodyType/"
                 (u/key->pascal ~k) "Body")))
 
 (defmacro body-def
+  "Returns a [BodyDef](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/physics/box2d/BodyDef.html)
+
+    (body-def :dynamic)
+"
   [k & options]
   `(let [^BodyDef object# (BodyDef.)]
      (set! (. object# type) ~(body-type k))
      (u/fields! object# ~@options)))
 
 (defmacro body!
+  "Calls a single method on a body"
   [entity k & options]
   `(let [^Body object# (u/get-obj ~entity :body)]
      (u/call! object# ~k ~@options)))
 
 (defn create-body!*
+  "The function version of `create-body!`"
   [screen b-def]
   (box-2d! screen :create-body b-def))
 
 (defmacro create-body!
+  "Returns a [Body](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/physics/box2d/Body.html)"
   [screen b-def & options]
   `(let [^Body object# (create-body!* ~screen ~b-def)]
      (u/calls! object# ~@options)))
 
 (defn body-x
+  "Returns the x position of the body in `entity`"
   [entity]
   (. (body! entity :get-position) x))
 
 (defn body-y
+  "Returns the y position of the body in `entity`"
   [entity]
   (. (body! entity :get-position) y))
 
 (defn body-angle
+  "Returns the angle of the body in `entity`"
   [entity]
   (.getRotation ^Transform (body! entity :get-transform)))
 
 (defn body-transform!
+  "Changes the `x`, `y`, and `angle` of the body in `entity`"
   [entity x y angle]
   (body! entity :set-transform x y angle)
   entity)
 
 (defn body-x!
+  "Changes the `x` of the body in `entity`"
   [entity x]
   (body-transform! entity x (body-y entity) (body-angle entity)))
 
 (defn body-y!
+  "Changes the `y` of the body in `entity`"
   [entity y]
   (body-transform! entity (body-x entity) y (body-angle entity)))
 
 (defn body-angle!
+  "Changes the `angle` of the body in `entity`"
   [entity angle]
   (body-transform! entity (body-x entity) (body-y entity) angle))
 
 ; joints
 
 (defmacro ^:private joint-init
+  "Internal use only"
   [k]
   `(symbol (str u/main-package ".physics.box2d.joints."
                 (u/key->pascal ~k) "JointDef.")))
 
 (defmacro joint-def
+  "Returns a [JointDef](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/physics/box2d/JointDef.html)
+
+    (joint-def :rope)
+"
   [k & options]
   `(let [object# (~(joint-init k))]
      (u/fields! object# ~@options)))
 
 (defmacro joint!
+  "Calls a single method on a joint"
   [object k & options]
   `(u/call! ^Joint ~object ~k ~@options))
 
 (defn create-joint!*
+  "The function version of `create-joint`"
   [screen j-def]
   (box-2d! screen :create-joint j-def))
 
 (defmacro create-joint!
+  "Returns a [Joint](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/physics/box2d/Joint.html)"
   [screen j-def & options]
   `(let [object# (create-joint!* ~screen ~j-def)]
      (u/calls! object# ~@options)))
@@ -109,30 +138,36 @@
 ; fixtures
 
 (defmacro fixture-def
+  "Returns a [FixtureDef](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/physics/box2d/FixtureDef.html)"
   [& options]
   `(let [^FixtureDef object# (FixtureDef.)]
      (u/fields! object# ~@options)
      object#))
 
 (defmacro fixture!
+  "Calls a single method on a fixture"
   [object k & options]
   `(u/call! ^Fixture ~object ~k ~@options))
 
 ; shapes
 
 (defn chain*
+  "The function version of `chain`"
   []
   (ChainShape.))
 
 (defmacro chain
+  "Returns a [ChainShape](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/physics/box2d/ChainShape.html)"
   [& options]
   `(u/calls! ^ChainShape (chain*) ~@options))
 
-(defmacro chain!-shape
+(defmacro chain-shape!
+  "Calls a single method on a `chain`"
   [object k & options]
   `(u/call! ^ChainShape ~object ~k ~@options))
 
 (defn circle*
+  "The function version of `circle`"
   ([]
     (CircleShape.))
   ([radius]
@@ -141,64 +176,74 @@
       (.setPosition (m/vector-2 radius radius)))))
 
 (defmacro circle
+  "Returns a [CircleShape](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/physics/box2d/CircleShape.html)"
   [radius & options]
   `(u/calls! ^CircleShape (circle* ~radius) ~@options))
 
 (defmacro circle!
+  "Calls a single method on a `circle`"
   [object k & options]
   `(u/call! ^CircleShape ~object ~k ~@options))
 
 (defn edge*
+  "The function version of `edge`"
   []
   (EdgeShape.))
 
 (defmacro edge
+  "Returns an [EdgeShape](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/physics/box2d/EdgeShape.html)"
   [& options]
   `(u/calls! ^EdgeShape (edge*) ~@options))
 
 (defmacro edge!
+  "Calls a single method on a `edge`"
   [object k & options]
   `(u/call! ^EdgeShape ~object ~k ~@options))
 
 (defn polygon*
+  "The function version of `polygon`"
   []
   (PolygonShape.))
 
 (defmacro polygon
+  "Returns a [PolygonShape](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/physics/box2d/PolygonShape.html)"
   [& options]
   `(u/calls! ^PolygonShape (polygon*) ~@options))
 
 (defmacro polygon!
+  "Calls a single method on a `polygon`"
   [object k & options]
   `(u/call! ^PolygonShape ~object ~k ~@options))
 
 ; misc
 
 (defmacro contact!
+  "Calls a single method on a [Contact](http://libgdx.badlogicgames.com/nightlies/docs/api/com/badlogic/gdx/physics/box2d/Contact.html)"
   [object k & options]
   `(u/call! ^Contact ~object ~k ~@options))
 
 (defn find-body
+  "Returns the first entity in `entities` whose body matches `body`"
   [body entities]
   (some #(if (= body (:body %)) %) entities))
 
-(defn first-contact
+(defn first-body
-  ([screen]
+  "Returns the first body in a contact"
-    (let [^Contact contact (u/get-obj screen :contact)]
+  [screen]
-      (assert contact)
+  (let [^Contact contact (u/get-obj screen :contact)]
-      (-> contact .getFixtureA .getBody)))
+    (assert contact)
-  ([screen entities]
+    (-> contact .getFixtureA .getBody)))
-    (find-body (first-contact screen) entities)))
 
-(defn second-contact
+(defn second-body
-  ([screen]
+  "Returns the second body in a contact"
-    (let [^Contact contact (u/get-obj screen :contact)]
+  [screen]
-      (assert contact)
+  (let [^Contact contact (u/get-obj screen :contact)]
-      (-> contact .getFixtureB .getBody)))
+    (assert contact)
-  ([screen entities]
+    (-> contact .getFixtureB .getBody)))
-    (find-body (second-contact screen) entities)))
 
 (defn step!
+  "Runs the physics simulations for a single frame and optionally returns the
+`entities` with their positions updated."
   ([{:keys [world time-step velocity-iterations position-iterations]
      :or {time-step (/ 1 60) velocity-iterations 10 position-iterations 10}}]
     (assert world)