+# A classic millisecond timer
+#
+# @example How to create a new timer
+#   var timer = new Rotten.Timer({ timeout: 1000, interval: 100 })
+#
 class Rotten.Timer extends Rotten.EventManager
 
+
+    # Constructs a new timer
+    #
+    # @param {Object} options Timer options
+    # @option options {int} timeout Your timeout (in milliseconds)
+    # @option options {int} interval Your interval (in milliseconds)
+    # @option options {boolean} autostart Whether you want your timer to autostart or not
     constructor: (options) ->
 
+        # The timeout of your timer
         @timeout = options.timeout or 10000
 
+        # The interval between two ticks or your timer
         @interval = options.interval or 1000
 
+        # Whether your timer should start automatically when initialized
         @autostart = options.autostart or true
 
+        # Whether your timer is active or not
         @active = options.autostart or true
 
+        # Current time of your timer
         @time = 0
 
+        # Last tick of your timer
         @lastTick = new Date()
 
         @.fire "start", { timeout: @timeout } if @autostart is true
 
 
+    # Updates your timer
+    # If your timer was not added to a scene, update() should be called on every
+    # round of your game loop (in the update queue)
     update: ->
         if @active is true
 

                @.fire "tick", { current: @time, remaining: @timeout - @time, completion: parseFloat @time / @timeout }


    reset: ->
        @time = 0
        @lastTick = new Date()

        if @autostart is true then @.restart() else @active = false


    # Stops your timer : nothing is counting time anymore. We are doomed.
    stop: ->
        @time = 0
        @lastTick = new Date()
        @.fire "stop", {}


    # Restarts your timer & fires a "start" event
    restart: ->
        @time = 0
        @lastTick = new Date()
