Update audio docs;

api/lovr/audio/getDopplerEffect.lua

@@ -1,10 +1,7 @@
 return {
   tag = 'listener',
   summary = 'Get the doppler effect parameters.',
-  description = [[
-    Returns the parameters that control the simulated doppler effect: The effect intensity and the
-    speed of sound.
-  ]],
+  description = 'Returns the parameters that control the simulated doppler effect.',
   arguments = {},
   returns = {
     {
@@ -18,5 +15,5 @@ return {
       description = 'The speed of sound, in meters per second.'
     }
   },
-  notes = 'The default factor is 1 and the default speed of sound is 343.29.'
+  notes = 'The default factor is 1.0 and the default speed of sound is 343.29.'
 }

api/lovr/audio/getMicrophoneNames.lua

@@ -1,7 +1,7 @@
 return {
   tag = 'microphones',
-  summary = 'Get a table containing the names of all connected microphones.',
-  description = 'Returns a table containing the names of all microphones connected to the system.',
+  summary = 'Get the names of all connected microphones.',
+  description = 'Returns a table with the names of all microphones connected to the system.',
   arguments = {
     t = {
       type = 'table',

api/lovr/audio/getOrientation.lua

@@ -26,5 +26,10 @@ return {
       type = 'number',
       description = 'The z component of the axis of rotation.'
     }
+  },
+  related = {
+    'lovr.audio.getPosition',
+    'lovr.audio.getPose',
+    'Source:getOrientation'
   }
 }

api/lovr/audio/getPose.lua

@@ -0,0 +1,48 @@
+return {
+  tag = 'listener',
+  summary = 'Get the pose of the listener.',
+  description = 'Returns the position and orientation of the virtual audio listener.',
+  arguments = {},
+  returns = {
+    {
+      name = 'x',
+      type = 'number',
+      description = 'The x position of the listener, in meters.'
+    },
+    {
+      name = 'y',
+      type = 'number',
+      description = 'The y position of the listener, in meters.'
+    },
+    {
+      name = 'z',
+      type = 'number',
+      description = 'The z position of the listener, in meters.'
+    },
+    {
+      name = 'angle',
+      type = 'number',
+      description = 'The number of radians the listener is rotated around its axis of rotation.'
+    },
+    {
+      name = 'ax',
+      type = 'number',
+      description = 'The x component of the axis of rotation.'
+    },
+    {
+      name = 'ay',
+      type = 'number',
+      description = 'The y component of the axis of rotation.'
+    },
+    {
+      name = 'az',
+      type = 'number',
+      description = 'The z component of the axis of rotation.'
+    }
+  },
+  related = {
+    'lovr.audio.getPosition',
+    'lovr.audio.getOrientation',
+    'Source:getPose'
+  }
+}

api/lovr/audio/isSpatialized.lua

@@ -1,10 +1,7 @@
 return {
   tag = 'listener',
   summary = 'Check if audio is spatialized.',
-  description = [[
-    Returns whether or not audio is currently spatialized with HRTFs.  Spatialized audio is much
-    more immersive.
-  ]],
+  description = 'Returns whether or not audio is currently spatialized with HRTFs.',
   arguments = {},
   returns = {
     {

api/lovr/audio/newMicrophone.lua

@@ -3,13 +3,18 @@ return {
   summary = 'Create a new Microphone.',
   description = [[
     Creates a new Microphone based on the name of an existing micrphone and a set of capture
-    parameters.  If the specified parameters are not supported, `nil` will be returned.
+    parameters.  If the specified combination of prameters are not supported for audio capture,
+    `nil` will be returned.
   ]],
   arguments = {
     {
       name = 'name',
       type = 'string',
-      description = 'The name of the microphone that this Microphone will record from.'
+      default = 'nil',
+      description = [[
+        The name of the microphone that this Microphone will record from, or `nil` to use the
+        default microphone.
+      ]]
     },
     {
       name = 'samples',

api/lovr/audio/pause.lua

@@ -3,5 +3,11 @@ return {
   summary = 'Pause all Sources.',
   description = 'Pause all playing audio.',
   arguments = {},
-  returns = {}
+  returns = {},
+  related = {
+    'Source:pause',
+    'lovr.audio.resume',
+    'lovr.audio.rewind',
+    'lovr.audio.stop'
+  }
 }

api/lovr/audio/resume.lua

@@ -3,5 +3,12 @@ return {
   summary = 'Resume all Sources.',
   description = 'Resume all Sources.  Has no effect on Sources that are playing or stopped.',
   arguments = {},
-  returns = {}
+  returns = {},
+  related = {
+    'Source:resume',
+    'Source:resume',
+    'lovr.audio.pause',
+    'lovr.audio.rewind',
+    'lovr.audio.stop'
+  }
 }

api/lovr/audio/rewind.lua

@@ -7,5 +7,11 @@ return {
   notes = [[
     Sources that are paused will remain paused. Sources that are currently playing will restart from
     the beginning.
-  ]]
+  ]],
+  related = {
+    'Source:rewind',
+    'lovr.audio.pause',
+    'lovr.audio.resume',
+    'lovr.audio.stop'
+  }
 }

api/lovr/audio/setDopplerEffect.lua

@@ -20,5 +20,5 @@ return {
     }
   },
   returns = {},
-  notes = 'The default factor is 1 and the default speed of sound is 343.29.'
+  notes = 'The default factor is 1.0 and the default speed of sound is 343.29.'
 }

api/lovr/audio/setPose.lua

@@ -0,0 +1,52 @@
+return {
+  tag = 'listener',
+  summary = 'Set the pose of the listener.',
+  description = 'Sets the position and orientation of the virtual audio listener.',
+  arguments = {
+    {
+      name = 'x',
+      type = 'number',
+      description = 'The x position of the listener, in meters.'
+    },
+    {
+      name = 'y',
+      type = 'number',
+      description = 'The y position of the listener, in meters.'
+    },
+    {
+      name = 'z',
+      type = 'number',
+      description = 'The z position of the listener, in meters.'
+    },
+    {
+      name = 'angle',
+      type = 'number',
+      description = 'The number of radians the listener is rotated around its axis of rotation.'
+    },
+    {
+      name = 'ax',
+      type = 'number',
+      description = 'The x component of the axis of rotation.'
+    },
+    {
+      name = 'ay',
+      type = 'number',
+      description = 'The y component of the axis of rotation.'
+    },
+    {
+      name = 'az',
+      type = 'number',
+      description = 'The z component of the axis of rotation.'
+    }
+  },
+  returns = {},
+  notes = [[
+    The default implementation of `lovr.run` calls this function with the result of
+    `lovr.headset.getPose`, so that the listener automatically tracks the headset.
+  ]],
+  related = {
+    'lovr.audio.setPosition',
+    'lovr.audio.setOrientation',
+    'Source:setPose'
+  }
+}

api/lovr/audio/stop.lua

@@ -4,7 +4,11 @@ return {
   description = 'Stops all audio.',
   arguments = {},
   returns = {},
-  notes = [[
-    If you want to resume the stopped audio later, see `lovr.audio.pause`.
-  ]]
+  notes = 'If you want to resume the stopped audio later, see `lovr.audio.pause`.',
+  related = {
+    'Source:stop',
+    'lovr.audio.pause',
+    'lovr.audio.resume',
+    'lovr.audio.rewind'
+  }
 }

api/lovr/audio/update.lua

@@ -2,8 +2,8 @@ return {
   tag = 'sources',
   summary = 'Updates the audio system.',
   description = [[
-    Updates all playing sources. This must be called regularly for audio playback to occur. Normally
-    this is called for you by `lovr.run`.
+    Updates all playing sources. This must be called regularly for audio playback to occur. This is
+    called automatically by the default implementation of `lovr.run`.
   ]],
   arguments = {},
   returns = {}