Small fixups;

api/init.lua

@@ -1398,14 +1398,24 @@ return {
               },
               variants = {
                 {
+                  description = "Get all available audio as a newly created `SoundData`.",
                   arguments = {},
-                  returns = {
-                    {
-                      name = "channels",
-                      type = "number",
-                      description = "The number of channels recorded."
-                    }
-                  }
+                  returns = {}
+                },
+                {
+                  description = "Get at most `sampleCount` samples from the microphone's internal queue as a newly created `SoundData`.",
+                  arguments = {},
+                  returns = {}
+                },
+                {
+                  description = "Get at all available audio and write it into `soundData`.",
+                  arguments = {},
+                  returns = {}
+                },
+                {
+                  description = "Get at all available audio and write it into `soundData` starting at `offset` samples into `soundData`.",
+                  arguments = {},
+                  returns = {}
                 }
               },
               notes = "There's a limit on the number of samples the Microphone is able to hold, which can be set at creation time in `lovr.audio.newMicrophone`.  While the Microphone is recording, be sure to call this function periodically to get a new chunk of audio in order to make room for more.\n\nYou can use `Microphone:getSampleCount` to figure out how many samples the Microphone is currently holding."
@@ -2146,6 +2156,7 @@ return {
               description = "Seeks the Source to the specified position.",
               key = "Source:seek",
               module = "lovr.audio",
+              notes = "This function can not be used on a Source backed by a raw `AudioStream`.",
               variants = {
                 {
                   arguments = {
@@ -2529,6 +2540,7 @@ return {
               description = "Returns the current playback position of the Source.",
               key = "Source:tell",
               module = "lovr.audio",
+              notes = "This function can not be used on a Source backed by a raw `AudioStream`.",
               variants = {
                 {
                   arguments = {
@@ -2566,11 +2578,12 @@ return {
         {
           name = "newAudioStream",
           summary = "Create a new AudioStream.",
-          description = "Creates a new AudioStream.  Right now, the only supported audio format is Ogg Vorbis (.ogg).",
+          description = "Creates a new AudioStream. AudioStream has two modes:\n\n- Constructed with a filename or blob, AudioStream will decode the given file on demand. Right\n  now, the only supported audio format is Ogg Vorbis (.ogg).\n- Constructed without, it's a \"raw\" audiostream that you append data to in real-time. See\n  `AudioStream:append` for usage.",
           key = "lovr.data.newAudioStream",
           module = "lovr.data",
           variants = {
             {
+              description = "Create an `AudioStream` decoding ogg audio from the file at `filename`.",
               arguments = {
                 {
                   name = "filename",
@@ -2593,6 +2606,7 @@ return {
               }
             },
             {
+              description = "Create an `AudioStream` decoding ogg audio from the given Blob.",
               arguments = {
                 {
                   name = "blob",
@@ -2613,6 +2627,36 @@ return {
                   description = "The new AudioStream."
                 }
               }
+            },
+            {
+              description = "Create a raw `AudioStream`.  You must call `append` to give it audio to stream later.",
+              arguments = {
+                {
+                  name = "channelCount",
+                  type = "number",
+                  description = "Number of audio channels (1 for mono or 2 for stereo)."
+                },
+                nil,
+                {
+                  name = "bufferSize",
+                  type = "number",
+                  description = "The size of the stream's audio buffer, in samples.",
+                  default = "4096"
+                },
+                {
+                  name = "queueLimit",
+                  type = "number",
+                  description = "        The maximum number of audio samples that this AudioStream will queue. The default is half a\n        second worth of data. Set to 0 for no limit (but be careful not to use too much RAM).\n      ",
+                  default = "sampleRate * 0.5"
+                }
+              },
+              returns = {
+                {
+                  name = "audioStream",
+                  type = "AudioStream",
+                  description = "The new AudioStream."
+                }
+              }
             }
           }
         },
@@ -2985,6 +3029,27 @@ return {
           key = "AudioStream",
           module = "lovr.data",
           methods = {
+            {
+              name = "append",
+              summary = "Append raw PCM audio data to this audio stream for playback.",
+              description = "Append audio data that you have constructed yourself (perhaps by generating it in code, or streaming it over the network).  Must only be called on a \"raw\" AudioStream (not one constructed with a file or a blob).\n\nThe data must be 16-bit signed integer, and the sample rate and channel count must match the values the AudioStream was constructed with.\n\nIf a call to `append` would make the internal buffer of this `AudioStream` to become bigger than the `queueLimit` set on this AudioStream when it was constructed, that call to `append` will ignore your blob and return false, queueing no data at all from that call.\n\nAfter you've created a Source with your raw AudioStream, and appended enough audio data, remember to call `Source:play` to make the `Source` start playing your queued data. If the `Source` plays all the audio data you've queued and thus runs out of data to play, it will automatically stop and you'll have to append more sound data and call `Source:play` again. You can use `AudioStream:getDuration` to see how much data has been queued so far.\n\nTry to have more audio queued than the time it will take before you call append() again to avoid stuttery playback. Having more than 0.2s audio queued at all times is a good guideline.",
+              key = "AudioStream:append",
+              module = "lovr.data",
+              related = {
+                "lovr.audio.newAudioStream",
+                "AudioStream:getDuration"
+              },
+              variants = {
+                {
+                  arguments = {},
+                  returns = {}
+                },
+                {
+                  arguments = {},
+                  returns = {}
+                }
+              }
+            },
             {
               name = "decode",
               summary = "Decode the next chunk of audio in the AudioStream.",
@@ -3411,6 +3476,29 @@ return {
                 }
               }
             },
+            {
+              name = "getBlob",
+              summary = "Get the bytes backing this SoundData as a `Blob`.",
+              description = "Returns a Blob containing the raw bytes of the SoundData.",
+              key = "SoundData:getBlob",
+              module = "lovr.data",
+              related = {
+                "Blob:getPointer",
+                "TextureData:getBlob"
+              },
+              variants = {
+                {
+                  arguments = {},
+                  returns = {
+                    {
+                      name = "blob",
+                      type = "Blob",
+                      description = "The Blob instance containing the bytes for the `SoundData`."
+                    }
+                  }
+                }
+              }
+            },
             {
               name = "getChannelCount",
               summary = "Get the number of channels in the SoundData.",
@@ -3604,6 +3692,29 @@ return {
                 }
               }
             },
+            {
+              name = "getBlob",
+              summary = "Get the bytes backing this TextureData as a `Blob`.",
+              description = "Returns a Blob containing the raw bytes of the TextureData.",
+              key = "TextureData:getBlob",
+              module = "lovr.data",
+              related = {
+                "Blob:getPointer",
+                "SoundData:getBlob"
+              },
+              variants = {
+                {
+                  arguments = {},
+                  returns = {
+                    {
+                      name = "blob",
+                      type = "Blob",
+                      description = "The Blob instance containing the bytes for the `TextureData`."
+                    }
+                  }
+                }
+              }
+            },
             {
               name = "getDimensions",
               summary = "Get the dimensions of the TextureData.",

api/lovr/audio/Microphone/getData.lua

@@ -7,44 +7,59 @@ return {
     {
       name = 'soundData',
       type = 'soundData',
-      description = 'The `SoundData` to fill with audio (instead of this method creating a new one).'
+      description = 'The `SoundData` to fill with audio (instead of creating a new one).'
     },
     {
       name = 'sampleCount',
       type = 'number',
-      description = 'How many samples of audio to get right now, at most. If less is available, you will get less.'
+      description = [[
+        How many samples of audio to get right now, at most. If less is available, you will get
+        less (use `Microphone:getSampleCount` to check the exact number).
+      ]]
     },
     {
       name = 'offset',
       type = 'number',
-      description = 'Index in samples into `soundData` at which to start to overwrite with new audio data from the microphone\'s internal buffer.'
+      description = [[
+        Index in samples into `soundData` at which to start to overwrite with new audio data from
+        the microphone's internal buffer.'
+      ]]
     }
   },
   returns = {
     {
       name = 'soundData',
       type = 'soundData',
-      description = 'A `SoundData` with `sampleCount` of samples in it (or less if less was available; or all if sampleCount was not given). Nothing is returned if no data is available.'
+      description = [[
+        A `SoundData` with `sampleCount` of samples in it (or less if less was available; or all if
+        sampleCount was not given). Nothing is returned if no data is available.
+      ]]
     }
   },
   variants = {
     {
-        description = "Get all available audio as a newly created `SoundData`",
-        arguments = { },
-        returns = { 'soundData' }
+      description = 'Get all available audio as a newly created `SoundData`.',
+      arguments = {},
+      returns = { 'soundData' }
     },
     {
-      description = "Get at most `sampleCount` samples from the microphone\'s internal queue as a newly created `SoundData`",
+      description = [[
+        Get at most `sampleCount` samples from the microphone's internal queue as a newly created
+        `SoundData`.
+      ]],
       arguments = { 'sampleCount' },
       returns = { 'soundData' }
     },
     {
-      description = "Get at all available audio and write it into `soundData`.",
+      description = 'Get at all available audio and write it into `soundData`.',
       arguments = { 'soundData' },
       returns = { 'soundData' }
     },
     {
-      description = "Get at all available audio and write it into `soundData` starting at 'offset' samples into `soundData`.",
+      description = [[
+        Get at all available audio and write it into `soundData` starting at `offset` samples into
+        `soundData`.
+      ]],
       arguments = { 'soundData', 'offset' },
       returns = { 'soundData' }
     }

api/lovr/audio/Source/seek.lua

@@ -1,6 +1,6 @@
 return {
   summary = 'Set the playback position of the Source.',
-  description = 'Seeks the Source to the specified position. Note that you may not `seek()` a `Source` backed by a raw `AudioStream`.',
+  description = 'Seeks the Source to the specified position.',
   arguments = {
     {
       name = 'position',
@@ -14,5 +14,6 @@ return {
       description = 'The units for the seek position.'
     }
   },
-  returns = {}
+  returns = {},
+  notes = 'This function can not be used on a Source backed by a raw `AudioStream`.'
 }

api/lovr/audio/Source/tell.lua

@@ -1,6 +1,6 @@
 return {
   summary = 'Get the playback position of the Source.',
-  description = 'Returns the current playback position of the Source. Note that you may not `tell()` a `Source` backed by a raw `AudioStream`.',
+  description = 'Returns the current playback position of the Source.',
   arguments = {
     {
       name = 'unit',
@@ -15,5 +15,6 @@ return {
       type = 'number',
       description = 'The current playback position.'
     }
-  }
+  },
+  notes = 'This function can not be used on a Source backed by a raw `AudioStream`.'
 }

api/lovr/data/AudioStream/append.lua

@@ -1,56 +1,66 @@
 return {
-    summary = 'Append raw PCM audio data to this audio stream for playback.',
-    description = [[
-      Append audio data that you have constructed yourself (perhaps by generating it in code, or streaming it over the network).
-      Must only be called on a "raw" AudioStream (not one constructed with a file or a blob).
+  summary = 'Append raw PCM audio data to this audio stream for playback.',
+  description = [[
+    Append audio data that you have constructed yourself (perhaps by generating it in code, or
+    streaming it over the network).  Must only be called on a "raw" AudioStream (not one
+    constructed with a file or a blob).
 
-      The data must be 16-bit signed integer, and the sample rate and channel count must match the values the AudioStream was
-      constructed with.
+    The data must be 16-bit signed integer, and the sample rate and channel count must match the
+    values the AudioStream was constructed with.
 
-      If a call to `append` would make the internal buffer of this `AudioStream` to become bigger than the `queueLimit` set 
-      on this AudioStream when it was constructed, that call to `append` will ignore your blob and return false, queueing
-      no data at all from that call.
-      
-      After you've created a Source with your raw AudioStream, and appended enough audio data, remember to call `Source:play()`
-      to make the `Source` start playing your queued data. If the `Source` plays all the audio data you've queued
-      and thus runs out of data to play, it will automatically stop and you'll have to append more sound data and call `Source:play()`
-      again. You can use `AudioStream:getDuration()` to see how much data has been queued so far. 
-      
-      Try to have more audio queued than the time it will take before you call append() again to avoid stuttery playback. Having
-      more than 0.2s audio queued at all times is a good guideline.
-    ]],
-    arguments = {
-        {
-            name = 'blob',
-            type = 'blob',
-            description = 'A `blob` of sound bytes. Since it has no information about the format of the data, `append` blindly trusts that you give it valid data.'
-        },
-        {
-            name = 'soundData',
-            type = 'soundData',
-            description = 'A SoundData blob of sound bytes. Lovr will assert if the format of the `SoundData` doesn\'t match the format of the `AudioStream`.'
-        },
-    },
-    returns = {
-      {
-        name = 'success',
-        type = 'bool',
-        description = 'True if this `append` did not exceed the queue limit, and data was thus appended to the queue; otherwise false.'
-      }
+    If a call to `append` would make the internal buffer of this `AudioStream` to become bigger
+    than the `queueLimit` set on this AudioStream when it was constructed, that call to `append`
+    will ignore your blob and return false, queueing no data at all from that call.
+
+    After you've created a Source with your raw AudioStream, and appended enough audio data,
+    remember to call `Source:play` to make the `Source` start playing your queued data. If the
+    `Source` plays all the audio data you've queued and thus runs out of data to play, it will
+    automatically stop and you'll have to append more sound data and call `Source:play` again.
+    You can use `AudioStream:getDuration` to see how much data has been queued so far.
+
+    Try to have more audio queued than the time it will take before you call append() again to
+    avoid stuttery playback. Having more than 0.2s audio queued at all times is a good guideline.
+  ]],
+  arguments = {
+    {
+      name = 'blob',
+      type = 'Blob',
+      description = [[
+        A Blob of sound bytes. Since it has no information about the format of the data,
+        `append` blindly trusts that you give it valid data.
+      ]]
     },
-    variants = {
-        {
-            arguments = { 'blob' },
-            returns = { 'success' }
-        },
-        {
-            arguments = { 'soundData' },
-            returns = { 'success' }
-        }
+    {
+      name = 'soundData',
+      type = 'SoundData',
+      description = [[
+        A SoundData blob of sound bytes.  The format of the `SoundData` must match the format
+        of the `AudioStream`.
+      ]]
     }
-    related = {
-      'lovr.audio.newAudioStream',
-      'AudioStream:getDuration'
+  },
+  returns = {
+    {
+      name = 'success',
+      type = 'boolean',
+      description = [[
+        Whether this `append` did not exceed the queue limit, and data was thus appended to the
+        queue.
+      ]]
+    }
+  },
+  variants = {
+    {
+      arguments = { 'blob' },
+      returns = { 'success' }
+    },
+    {
+      arguments = { 'soundData' },
+      returns = { 'success' }
     }
+  },
+  related = {
+    'lovr.audio.newAudioStream',
+    'AudioStream:getDuration'
   }
-  
+}

api/lovr/data/SoundData/getBlob.lua

@@ -1,13 +1,16 @@
 return {
-    summary = 'Get the bytes backing this SoundData as a `Blob`.',
-    description = 'This replaces `SoundData:getPointer()`, since you can get that through the blob.',
-    arguments = {},
-    returns = {
-      {
-        name = 'blob',
-        type = 'blob',
-        description = 'The blob instance containing the bytes for the `SoundData`.'
-      }
+  summary = 'Get the bytes backing this SoundData as a `Blob`.',
+  description = 'Returns a Blob containing the raw bytes of the SoundData.',
+  arguments = {},
+  returns = {
+    {
+      name = 'blob',
+      type = 'Blob',
+      description = 'The Blob instance containing the bytes for the `SoundData`.'
     }
+  },
+  related = {
+    'Blob:getPointer',
+    'TextureData:getBlob'
   }
-  
+}

api/lovr/data/TextureData/getBlob.lua

@@ -1,13 +1,16 @@
 return {
-    summary = 'Get the bytes backing this `TextureData` as a `Blob`.',
-    description = 'This replaces `TextureData:getPointer()`, since you can get that through the blob.',
-    arguments = {},
-    returns = {
-      {
-        name = 'blob',
-        type = 'blob',
-        description = 'The blob instance containing the bytes for the `TextureData`.'
-      }
+  summary = 'Get the bytes backing this TextureData as a `Blob`.',
+  description = 'Returns a Blob containing the raw bytes of the TextureData.',
+  arguments = {},
+  returns = {
+    {
+      name = 'blob',
+      type = 'Blob',
+      description = 'The Blob instance containing the bytes for the `TextureData`.'
     }
+  },
+  related = {
+    'Blob:getPointer',
+    'SoundData:getBlob'
   }
-  
+}

api/lovr/data/newAudioStream.lua

@@ -3,8 +3,10 @@ return {
   description = [[
     Creates a new AudioStream. AudioStream has two modes:
 
-    1. Constructed with a filename or blob, AudioStream will decode the given file on demand. Right now, the only supported audio format is Ogg Vorbis (.ogg).
-    2. Constructed without, it's a "raw" audiostream that you append data to in real-time. See `AudioStream:append` for usage.
+    - Constructed with a filename or blob, AudioStream will decode the given file on demand. Right
+      now, the only supported audio format is Ogg Vorbis (.ogg).
+    - Constructed without, it's a "raw" audiostream that you append data to in real-time. See
+      `AudioStream:append` for usage.
   ]],
   arguments = {
     filename = {
@@ -22,12 +24,15 @@ return {
     },
     queueLimit = {
       type = 'number',
-      default = 'sampleRate*0.5',
-      description = 'The maximum number of audio samples that this AudioStream will queue. The default is half a second worth of data. Set to 0 for no limit (but be careful not to use too much RAM).'
+      default = 'sampleRate * 0.5',
+      description = [[
+        The maximum number of audio samples that this AudioStream will queue. The default is half a
+        second worth of data. Set to 0 for no limit (but be careful not to use too much RAM).
+      ]]
     },
     channelCount = {
       type = 'number',
-      description = 'Number of audio channels (1 for mono or 2 for stereo)'
+      description = 'Number of audio channels (1 for mono or 2 for stereo).'
     }
   },
   returns = {
@@ -38,17 +43,19 @@ return {
   },
   variants = {
     {
-      description = 'Create an `AudioStream` decoding ogg audio from the file at `filename`',
+      description = 'Create an `AudioStream` decoding ogg audio from the file at `filename`.',
       arguments = { 'filename', 'bufferSize' },
       returns = { 'audioStream' }
     },
     {
-      description = 'Create an `AudioStream` decoding ogg audio from the given blob.',
+      description = 'Create an `AudioStream` decoding ogg audio from the given Blob.',
       arguments = { 'blob', 'bufferSize' },
       returns = { 'audioStream' }
     },
     {
-      description = 'Create a raw `AudioStream`. You must call `append` to give it audio to stream later.',
+      description = [[
+        Create a raw `AudioStream`.  You must call `append` to give it audio to stream later.
+      ]],
       arguments = { 'channelCount', 'sampleRate', 'bufferSize', 'queueLimit'},
       returns = { 'audioStream' }
     }