Permalink
Browse files

fix up documentation

  • Loading branch information...
1 parent 63d4cda commit 5ebda33a38ca62191fcf5b34060bc997b482a1c2 @ztellman committed May 9, 2010
View
@@ -7,4 +7,5 @@ penumbra.ipr
/native/*
/autodoc/*
penumbra.jar
-pom.xml
+pom.xml
+META-INF
View
@@ -6,5 +6,6 @@
[org.clojure/clojure-contrib "1.2.0-SNAPSHOT"]]
:native-dependencies [[penumbra/lwjgl "2.4.2"]]
:dev-dependencies [[native-deps "1.0.0"]
+ [autodoc "0.7.1"]
[lein-clojars "0.5.0-SNAPSHOT"]
[leiningen/lein-swank "1.1.0"]])
View
@@ -44,7 +44,9 @@
(next args)))))
arglists)))
-(defmacro- auto-extend [type protocol template & explicit]
+(defmacro- auto-extend
+ "Lets the application, which contains an implementation of a protocol, automatically extend that protocol."
+ [type protocol template & explicit]
(let [sigs (eval `(vals (:sigs ~protocol)))]
(list
`extend
@@ -62,7 +64,9 @@
;;;
-(defn- update- [app state f args]
+(defn- update-
+ "Updates the state of the application."
+ [app state f args]
(swap! state
(fn [state]
(let [state* (if (empty? args)
@@ -72,7 +76,9 @@
(controller/invalidated! app true))
(or state* state)))))
-(defn- alter-callbacks [clock callbacks]
+(defn- alter-callbacks
+ "Updates the update and display callbacks using timed-fn"
+ [clock callbacks]
(let [wrap (partial loop/timed-fn clock)
callbacks (if (:update callbacks)
(update-in callbacks [:update] wrap)
@@ -122,7 +128,9 @@
(defmethod print-method penumbra.app.App [app writer]
(.write writer "App"))
-(defn create [callbacks state]
+(defn create
+ "Creates an application."
+ [callbacks state]
(let [window (atom nil)
input (atom nil)
queue (atom nil)
@@ -142,12 +150,15 @@
;;;
-(defn app []
+(defn app
+ "Returns the current application."
+ []
app/*app*)
-(defn- transform-import-arglists [protocol name arglists]
+(defn- transform-import-arglists [protocol name doc arglists]
(list*
`defn name
+ doc
(map
(fn [args]
(list
@@ -158,13 +169,15 @@
(next args))))
arglists)))
-(defmacro- auto-import [protocol & imports]
+(defmacro- auto-import
+ "Creates an function which automatically fills in app with *app*"
+ [protocol & imports]
(let [sigs (eval `(vals (:sigs ~protocol)))]
(list*
'do
(map
- (fn [{name :name arglists :arglists}]
- (transform-import-arglists protocol name arglists))
+ (fn [{name :name arglists :arglists doc :doc}]
+ (transform-import-arglists protocol name doc arglists))
(let [imports (set imports)]
(filter #(imports (:name %)) sigs))))))
@@ -180,45 +193,68 @@
;;
(defn clock
+ "Returns the application clock."
([] (clock app/*app*))
([app] (:clock app)))
(defn now
+ "Returns the elapsed clock time, in seconds, since the application began."
([] (now app/*app*))
([app] @(clock app)))
(defn speed!
+ "Sets the application clock speed."
([speed] (speed! app/*app* speed))
([app speed] (time/speed! (clock app) speed)))
(defn periodic-update!
+ "Starts a recurring update, which is called 'hz' times a second.
+ Time is governed by 'clock', which defaults to the application clock.
+
+ OpenGL calls cannot be made within this callback."
([hz f] (periodic-update! (clock) hz f))
([clock hz f] (periodic-update! app/*app* clock hz f))
([app clock hz f] (queue/periodic-enqueue! app clock hz #(update- app (:state app) f nil))))
(defn delay!
+ "Enqueues an update to be executed in 'delay' milliseconds.
+ Time is goverend by 'clock', which defaults to the application clock.
+
+ OpenGL calls cannot be made within this callback."
([delay f] (delay! (clock) delay f))
([clock delay f] (delay! app/*app* clock delay f))
([app clock delay f] (queue/enqueue! app clock delay #(update- app (:state app) f nil))))
(defn update!
+ "Enqueues an update to happen immediately.
+
+ OpenGL calls cannot be made within the callback."
([f] (update! app/*app* f))
([app f] (delay! (clock app) 0 f)))
(defn enqueue!
+ "Enqueues an update to happen before the next frame is rendered.
+
+ OpenGL calls in this callback are okay."
([f] (enqueue! app/*app* f))
([app f] (event/subscribe-once! app :enqueue #(update- app (:state app) f nil))))
(defn repaint!
+ "Forces the application to repaint."
([] (repaint! app/*app*))
([app] (controller/invalidated! app true)))
(defn frequency! [hz]
+ "Updates the update frequency of a periodic update.
+
+ This can only be called from within the periodic callback. A frequency of 0 or less will halt the update."
(reset! app/*hz* hz))
;;
-(defmacro with-gl [& body]
+(defmacro with-gl
+ "Creates a valid OpenGL context within the scope."
+ [& body]
`(slate/with-slate
(context/with-context nil
~@body)))
@@ -245,7 +281,8 @@
(if (window/close? app)
(controller/stop! app :requested-by-user))))
-(defn start-single-thread [app loop-fn]
+(defn start-single-thread
+ [app loop-fn]
(context/with-context nil
(loop-fn
app
@@ -1,24 +0,0 @@
-;; Copyright (c) Zachary Tellman. All rights reserved.
-;; The use and distribution terms for this software are covered by the
-;; Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
-;; which can be found in the file epl-v10.html at the root of this distribution.
-;; By using this software in any fashion, you are agreeing to be bound by
-;; the terms of this license.
-;; You must not remove this notice, or any other, from this
-;; software.
-
-(ns penumbra.app.awt
- (:require [penumbra.app
- [event :as event]
- [controller :as controller]])
- (:use [penumbra.app.core])
- (:import [org.lwjgl.opengl AWTGLCanvas]))
-
-(defn create [app]
- (let [canvas-ref (atom nil)]
- (reset!
- canvas-ref
- (proxy [AWTGLCanvas] []
- (update [_])
- (paintGL []
- )))))
@@ -12,14 +12,14 @@
;;;
(defprotocol Controller
- (paused? [c])
- (pause! [c])
- (stopped? [c])
- (stop! [c] [c flag])
- (resume! [c])
- (invalidated? [c])
- (invalidated! [c flag])
- (wait! [c]))
+ (paused? [c] "Returns true if the application is paused.")
+ (pause! [c] "Pauses the application.")
+ (stopped? [c] "Returns true if the application is stopped.")
+ (stop! [c] [c flag] "Stops the application.")
+ (resume! [c] "Resumes the application. If the application is currently running, this is a no-op.")
+ (invalidated? [c] "Returns true if the application needs to be repainted.")
+ (invalidated! [c flag] "Sets whether the application needs to be repainted.")
+ (wait! [c] "Halts execution of the thread if application is paused or stops. The thread will resume once the application does."))
;;;
@@ -9,10 +9,10 @@
(ns penumbra.app.event)
(defprotocol EventHandler
- (subscribe! [event hook f] "Subscribe to an event.")
- (unsubscribe! [event hook f])
- (subscribe-once! [event hook f])
- (publish- [event hook args]))
+ (subscribe! [event hook f] "Subscribe to event 'hook' with callback 'f'.")
+ (unsubscribe! [event hook f] "Unsubscribes callback 'f' from event 'hook'")
+ (subscribe-once! [event hook f] "Subscribes callback 'f'. Once the callback is triggered, it is unsubscribed.")
+ (publish- [event hook args] "Publishes an event. Any callbacks will be invoked with 'args'"))
(defn create []
(let [event (ref {})]
@@ -16,14 +16,14 @@
;;;
(defprotocol InputHandler
- (init! [i])
- (destroy! [i])
- (key-repeat! [i flag])
- (key-pressed? [i key])
- (button-pressed? [i button])
- (mouse-location [i])
- (handle-mouse! [i])
- (handle-keyboard! [i]))
+ (init! [i] "Initialize the input handler.")
+ (destroy! [i] "Clean up the input handlers.")
+ (key-repeat! [i flag] "Sets whether a constantly pressed key triggers multiple key-press events.")
+ (key-pressed? [i key] "Checks whether a key is currently pressed.")
+ (button-pressed? [i button] "Checks whether a mouse button is currently presseed.")
+ (mouse-location [i] "Returns the current location of the mouse. [0 0] is the upper-left corner.")
+ (handle-mouse! [i] "Handle mouse input.")
+ (handle-keyboard! [i] "Mouse keyboard input."))
;;Keyboard
@@ -17,7 +17,9 @@
;;;
-(defn timed-fn [clock f]
+(defn timed-fn
+ "Creates a wrapper function which prepends any arguments with [dt t] in seconds."
+ [clock f]
(when f
(let [previous (atom @clock)]
(fn [& args]
@@ -27,11 +29,12 @@
(finally
(reset! previous now))))))))
-(defn create-thread [app outer-fn inner-fn]
+(defn create-thread
+ "Creates a thread. 'outer-fn' is passed 'inner-fn' as its only argument."
+ [app outer-fn inner-fn]
(Thread.
#(with-app app
- (outer-fn
- (inner-fn)))))
+ (outer-fn inner-fn))))
(defn pauseable-loop
[app outer-fn inner-fn]
@@ -14,10 +14,10 @@
;;;
(defprotocol Queue
- (init- [q])
- (start-consumer-thread [q])
- (enqueue- [q delay f])
- (periodic-enqueue- [q hz f]))
+ (init- [q] "Initializes action queue.")
+ (start-consumer-thread [q] "Starts a consumer thread for queue.")
+ (enqueue- [q delay f] "Enqueues an action to be executed in 'delay' milliseconds")
+ (periodic-enqueue- [q hz f] "Creates a recurring action to be executed 'hz' times a second"))
(defn- create-queue [app clock]
(let [heap (ref (sorted-set-by #(- (compare (first %2) (first %1)))))
@@ -24,21 +24,21 @@
;;;
(defprotocol Window
- (display-modes [w])
- (display-mode [w])
- (display-mode! [window w h] [w mode])
- (title! [w title])
- (size [w])
- (resized? [w])
- (invalidated? [w])
- (close? [w])
- (process! [w])
- (update! [w])
- (handle-resize! [w])
- (init! [w])
- (destroy! [w])
- (vsync! [w flag])
- (fullscreen! [w flag]))
+ (display-modes [w] "Returns all display modes supported by the display device.")
+ (display-mode [w] "Returns the current display mode.")
+ (display-mode! [window w h] [w mode] "Sets the display mode.")
+ (title! [w title] "Sets the title of the application.")
+ (size [w] "Returns the current size of the application.")
+ (resized? [w] "Returns true if application was resized since handle-resize! was last called.")
+ (invalidated? [w] "Returns true if the window is invalidated by the operating system.")
+ (close? [w] "Returns true if the user has requested it be closed.")
+ (process! [w] "Processes all messages from the operating system.")
+ (update! [w] "Swaps the buffers.")
+ (handle-resize! [w] "Handles any resize events. If there wasn't a resizing, this is a no-op.")
+ (init! [w] "Initializes the window.")
+ (destroy! [w] "Destroys the window.")
+ (vsync! [w flag] "Toggles vertical sync.")
+ (fullscreen! [w flag] "Toggles fullscreen mode."))
;;;
View
@@ -27,14 +27,3 @@
(defn update [node event & args]
(update- node event args))
-
-(defprotocol TestP
- (f [x y z]))
-
-(deftype TestT [a])
-
-(def t (TestT (reify TestP (f [x y z] (+ y z)))))
-
-
-
-(auto-extend ::TestT TestP (:a this))
@@ -1,12 +0,0 @@
-;; Copyright (c) Zachary Tellman. All rights reserved.
-;; The use and distribution terms for this software are covered by the
-;; Eclipse Public License 1.0 (http://opensource.org/licenses/eclipse-1.0.php)
-;; which can be found in the file epl-v10.html at the root of this distribution.
-;; By using this software in any fashion, you are agreeing to be bound by
-;; the terms of this license.
-;; You must not remove this notice, or any other, from this software.
-
-(ns penumbra.node.core)
-
-(defn create [callbacks state]
- )
Oops, something went wrong. Retry.

0 comments on commit 5ebda33

Please sign in to comment.