Merge pull request #5 from mcclure/errhand-run

Expand lovr.errhand and lovr.run docs

api/lovr/callbacks/errhand.lua

@@ -2,9 +2,18 @@ return {
   tag = 'callbacks',
   summary = 'Called when an error occurs.',
   description = [[
-    The `lovr.errhand` callback is run whenever an error occurs.  It receives a single string
-    parameter containing the error message.  It should return a function to run in a loop to show
-    the error screen.
+    The "lovr.errhand" callback is run whenever an error occurs.  It receives two
+    parameters. The first is a string containing the error message. The second is either
+    nil, or a string containing a traceback (as returned by "debug.traceback()"); if nil,
+    this means "lovr.errhand" is being called in the stack where the error occurred,
+    and it can call "debug.traceback()" itself.
+
+    "lovr.errhand" should return a handler function to run in a loop to show
+    the error screen. This handler function is of the same type as the one returned by
+    "lovr.run" and has the same requirements (such as pumping events). If an error occurs
+    while this handler is running, the program will terminate immediately--
+    "lovr.errhand" will not be given a second chance. Errors which occur inside "lovr.errhand"
+    or in the handler it returns may not be cleanly reported, so be careful.
 
     A default error handler is supplied that renders the error message as text to the headset and
     to the window.
@@ -14,18 +23,35 @@ return {
       name = 'message',
       type = 'string',
       description = 'The error message.'
+    },
+    {
+      name = 'traceback',
+      type = 'string',
+      description = 'A traceback string, or nil.'
     }
   },
   returns = {
     {
       name = 'handler',
       type = 'function',
-      description = 'The error handler function.'
+      arguments = {},
+      returns = {
+        {
+          name = 'result',
+          type = '*'
+        }
+      },
+      description = [[
+        The error handler function.  It should return nil to continue running, "restart" to restart the
+        app, or a number representing an exit status.
+      ]]
     }
   },
   example = [[
-    function lovr.errhand(message)
+    function lovr.errhand(message, traceback)
+      traceback = traceback or debug.traceback('', 3)
       print('ohh NOOOO!', message)
+      print(traceback)
       return function()
         lovr.graphics.print('There was an error', 0, 2, -5)
       end

api/lovr/callbacks/run.lua

@@ -20,6 +20,11 @@ return {
       description = [[
         The main loop function.  It should return nil to continue running, "restart" to restart the
         app, or a number representing an exit status.
+
+        Most users should overload lovr.load, lovr.update and lovr.draw instead, since if a custom lovr.run
+        does not do everything it is expected to some features may not work. For example, if lovr.run does
+        not respond to "quit" events the program will not be able to quit, and if it does not call "present"
+        then no graphics will be drawn.
       ]]
     }
   },