1 files changed, 62 insertions, 10 deletions
diff --git a/meta/3rd/lovr/library/lovr.thread.lua b/meta/3rd/lovr/library/lovr.thread.lua
index ca329a6b..08619426 100644
--- a/meta/3rd/lovr/library/lovr.thread.lua
+++ b/meta/3rd/lovr/library/lovr.thread.lua
@@ -5,18 +5,26 @@
 ---
 ---These are operating system level threads, which are different from Lua coroutines.
 ---
----Threads are useful for performing expensive background computation without affecting the framerate or performance of the main thread.  Some examples of this include asset loading, networking and network requests, and physics simulation.
+---Threads are useful for performing expensive background computation without affecting the framerate or performance of the main thread.
+---
+---Some examples of this include asset loading, networking and network requests, and physics simulation.
 ---
 ---Threads come with some caveats:
 ---
----- Threads run in a bare Lua environment.  The `lovr` module (and any of lovr's modules) need to
+---- Threads run in a bare Lua environment.
+---
+---The `lovr` module (and any of lovr's modules) need to
 ---  be required before they can be used.
 ---  - To get `require` to work properly, add `require 'lovr.filesystem'` to the thread code.
----- Threads are completely isolated from other threads.  They do not have access to the variables
+---- Threads are completely isolated from other threads.
+---
+---They do not have access to the variables
 ---  or functions of other threads, and communication between threads must be coordinated through
 ---  `Channel` objects.
 ---- The graphics module (or any functions that perform rendering) cannot be used in a thread.
----  Note that this includes creating graphics objects like Models and Textures.  There are "data"
+---  Note that this includes creating graphics objects like Models and Textures.
+---
+---There are "data"
 ---  equivalent `ModelData` and `Image` objects that can be used in threads though.
 ---- `lovr.event.pump` cannot be called from a thread.
 ---- Crashes or problems can happen if two threads access the same object at the same time, so
@@ -35,6 +43,16 @@ function lovr.thread.getChannel(name) end
 ---
 ---Creates a new Thread from Lua code.
 ---
+---
+---### NOTE:
+---The Thread won\'t start running immediately.
+---
+---Use `Thread:start` to start it.
+---
+---The string argument is assumed to be a filename if there isn't a newline in the first 1024 characters.
+---
+---For really short thread code, an extra newline can be added to trick LÖVR into loading it properly.
+---
 ---@overload fun(filename: string):lovr.Thread
 ---@overload fun(blob: lovr.Blob):lovr.Thread
 ---@param code string # The code to run in the Thread.
@@ -42,7 +60,13 @@ function lovr.thread.getChannel(name) end
 function lovr.thread.newThread(code) end
 
 ---
----A Channel is an object used to communicate between `Thread` objects.  Channels are obtained by name using `lovr.thread.getChannel`.  Different threads can send messages on the same Channel to communicate with each other.  Messages can be sent and received on a Channel using `Channel:push` and `Channel:pop`, and are received in a first-in-first-out fashion. The following types of data can be passed through Channels: nil, boolean, number, string, and any LÖVR object.
+---A Channel is an object used to communicate between `Thread` objects.
+---
+---Channels are obtained by name using `lovr.thread.getChannel`.
+---
+---Different threads can send messages on the same Channel to communicate with each other.
+---
+---Messages can be sent and received on a Channel using `Channel:push` and `Channel:pop`, and are received in a first-in-first-out fashion. The following types of data can be passed through Channels: nil, boolean, number, string, and any LÖVR object.
 ---
 ---@class lovr.Channel
 local Channel = {}
@@ -53,28 +77,52 @@ local Channel = {}
 function Channel:clear() end
 
 ---
----Returns whether or not the message with the given ID has been read.  Every call to `Channel:push` returns a message ID.
+---Returns whether or not the message with the given ID has been read.
+---
+---Every call to `Channel:push` returns a message ID.
 ---
 ---@param id number # The ID of the message to check.
 ---@return boolean read # Whether the message has been read.
 function Channel:hasRead(id) end
 
 ---
----Returns a message from the Channel without popping it from the queue.  If the Channel is empty, `nil` is returned.  This can be useful to determine if the Channel is empty.
+---Returns a message from the Channel without popping it from the queue.
+---
+---If the Channel is empty, `nil` is returned.
+---
+---This can be useful to determine if the Channel is empty.
+---
+---
+---### NOTE:
+---The second return value can be used to detect if a `nil` message is in the queue.
 ---
 ---@return any message # The message, or `nil` if there is no message.
 ---@return boolean present # Whether a message was returned (use to detect nil).
 function Channel:peek() end
 
 ---
----Pops a message from the Channel.  If the Channel is empty, an optional timeout argument can be used to wait for a message, otherwise `nil` is returned.
+---Pops a message from the Channel.
+---
+---If the Channel is empty, an optional timeout argument can be used to wait for a message, otherwise `nil` is returned.
+---
+---
+---### NOTE:
+---Threads can get stuck forever waiting on Channel messages, so be careful.
 ---
 ---@param wait? number # How long to wait for a message to be popped, in seconds.  `true` can be used to wait forever and `false` can be used to avoid waiting.
 ---@return any message # The received message, or `nil` if nothing was received.
 function Channel:pop(wait) end
 
 ---
----Pushes a message onto the Channel.  The following types of data can be pushed: nil, boolean, number, string, and userdata.  Tables should be serialized to strings.
+---Pushes a message onto the Channel.
+---
+---The following types of data can be pushed: nil, boolean, number, string, and userdata.
+---
+---Tables should be serialized to strings.
+---
+---
+---### NOTE:
+---Threads can get stuck forever waiting on Channel messages, so be careful.
 ---
 ---@param message any # The message to push.
 ---@param wait? number # How long to wait for the message to be popped, in seconds.  `true` can be used to wait forever and `false` can be used to avoid waiting.
@@ -83,7 +131,11 @@ function Channel:pop(wait) end
 function Channel:push(message, wait) end
 
 ---
----A Thread is an object that runs a chunk of Lua code in the background.  Threads are completely isolated from other threads, meaning they have their own Lua context and can't access the variables and functions of other threads.  Communication between threads is limited and is accomplished by using `Channel` objects.
+---A Thread is an object that runs a chunk of Lua code in the background.
+---
+---Threads are completely isolated from other threads, meaning they have their own Lua context and can't access the variables and functions of other threads.
+---
+---Communication between threads is limited and is accomplished by using `Channel` objects.
 ---
 ---To get `require` to work properly, add `require 'lovr.filesystem'` to the thread code.
 ---