Merge commit 'b37ebceffe695defd7e7976e653ce127618614c0' into 3.0

1 files changed, 127 insertions, 9 deletions

diff --git a/meta/3rd/lovr/library/lovr.filesystem.lua b/meta/3rd/lovr/library/lovr.filesystem.lua
index 37fe8e0e..4f8214db 100644
--- a/meta/3rd/lovr/library/lovr.filesystem.lua
+++ b/meta/3rd/lovr/library/lovr.filesystem.lua
@@ -3,12 +3,40 @@
 ---
 ---The `lovr.filesystem` module provides access to the filesystem.
 ---
+---
+---### NOTE:
+---LÖVR programs can only write to a single directory, called the save directory.
+---
+---The location of the save directory is platform-specific:
+---
+---<table>
+---  <tr>
+---    <td>Windows</td>
+---    <td><code>C:\Users\&lt;user&gt;\AppData\Roaming\LOVR\&lt;identity&gt;</code></td>
+---  </tr>
+---  <tr>
+---    <td>macOS</td>
+---    <td><code>/Users/&lt;user&gt;/Library/Application Support/LOVR/&lt;identity&gt;</code></td>
+---  </tr> </table>
+---
+---`<identity>` should be a unique identifier for your app.
+---
+---It can be set either in `lovr.conf` or by using `lovr.filesystem.setIdentity`.
+---
+---All filenames are relative to either the save directory or the directory containing the project source.
+---
+---Files in the save directory take precedence over files in the project.
+---
 ---@class lovr.filesystem
 lovr.filesystem = {}
 
 ---
 ---Appends content to the end of a file.
 ---
+---
+---### NOTE:
+---If the file does not exist, it is created.
+---
 ---@overload fun(filename: string, blob: lovr.Blob):number
 ---@param filename string # The file to append to.
 ---@param content string # A string to write to the end of the file.
@@ -16,14 +44,18 @@ lovr.filesystem = {}
 function lovr.filesystem.append(filename, content) end
 
 ---
----Creates a directory in the save directory.  Any parent directories that don't exist will also be created.
+---Creates a directory in the save directory.
+---
+---Any parent directories that don't exist will also be created.
 ---
 ---@param path string # The directory to create, recursively.
 ---@return boolean success # Whether the directory was created.
 function lovr.filesystem.createDirectory(path) end
 
 ---
----Returns the application data directory.  This will be something like:
+---Returns the application data directory.
+---
+---This will be something like:
 ---
 ---- `C:\Users\user\AppData\Roaming` on Windows.
 ---- `/home/user/.config` on Linux.
@@ -35,6 +67,10 @@ function lovr.filesystem.getAppdataDirectory() end
 ---
 ---Returns a sorted table containing all files and folders in a single directory.
 ---
+---
+---### NOTE:
+---This function calls `table.sort` to sort the results, so if `table.sort` is not available in the global scope the results are not guaranteed to be sorted.
+---
 ---@param path string # The directory.
 ---@return lovr.items table # A table with a string for each file and subfolder in the directory.
 function lovr.filesystem.getDirectoryItems(path) end
@@ -46,7 +82,15 @@ function lovr.filesystem.getDirectoryItems(path) end
 function lovr.filesystem.getExecutablePath() end
 
 ---
----Returns the identity of the game, which is used as the name of the save directory.  The default is `default`.  It can be changed using `t.identity` in `lovr.conf`.
+---Returns the identity of the game, which is used as the name of the save directory.
+---
+---The default is `default`.
+---
+---It can be changed using `t.identity` in `lovr.conf`.
+---
+---
+---### NOTE:
+---On Android, this is always the package id (like `org.lovr.app`).
 ---
 ---@return string identity # The name of the save directory, or `nil` if it isn't set.
 function lovr.filesystem.getIdentity() end
@@ -59,14 +103,26 @@ function lovr.filesystem.getIdentity() end
 function lovr.filesystem.getLastModified(path) end
 
 ---
----Get the absolute path of the mounted archive containing a path in the virtual filesystem.  This can be used to determine if a file is in the game's source directory or the save directory.
+---Get the absolute path of the mounted archive containing a path in the virtual filesystem.
+---
+---This can be used to determine if a file is in the game's source directory or the save directory.
 ---
 ---@param path string # The path to check.
 ---@return string realpath # The absolute path of the mounted archive containing `path`.
 function lovr.filesystem.getRealDirectory(path) end
 
 ---
----Returns the require path.  The require path is a semicolon-separated list of patterns that LÖVR will use to search for files when they are `require`d.  Any question marks in the pattern will be replaced with the module that is being required.  It is similar to Lua\'s `package.path` variable, but the main difference is that the patterns are relative to the virtual filesystem.
+---Returns the require path.
+---
+---The require path is a semicolon-separated list of patterns that LÖVR will use to search for files when they are `require`d.
+---
+---Any question marks in the pattern will be replaced with the module that is being required.
+---
+---It is similar to Lua\'s `package.path` variable, but the main difference is that the patterns are relative to the virtual filesystem.
+---
+---
+---### NOTE:
+---The default reqiure path is '?.lua;?/init.lua'.
 ---
 ---@return string path # The semicolon separated list of search patterns.
 function lovr.filesystem.getRequirePath() end
@@ -74,12 +130,24 @@ function lovr.filesystem.getRequirePath() end
 ---
 ---Returns the absolute path to the save directory.
 ---
+---
+---### NOTE:
+---The save directory takes the following form:
+---
+---``` <appdata>/LOVR/<identity> ```
+---
+---Where `<appdata>` is `lovr.filesystem.getAppdataDirectory` and `<identity>` is `lovr.filesystem.getIdentity` and can be customized using `lovr.conf`.
+---
 ---@return string path # The absolute path to the save directory.
 function lovr.filesystem.getSaveDirectory() end
 
 ---
 ---Returns the size of a file, in bytes.
 ---
+---
+---### NOTE:
+---If the file does not exist, an error is thrown.
+---
 ---@param file string # The file.
 ---@return number size # The size of the file, in bytes.
 function lovr.filesystem.getSize(file) end
@@ -97,7 +165,9 @@ function lovr.filesystem.getSource() end
 function lovr.filesystem.getUserDirectory() end
 
 ---
----Returns the absolute path of the working directory.  Usually this is where the executable was started from.
+---Returns the absolute path of the working directory.
+---
+---Usually this is where the executable was started from.
 ---
 ---@return string path # The current working directory, or `nil` if it's unknown.
 function lovr.filesystem.getWorkingDirectory() end
@@ -125,12 +195,26 @@ function lovr.filesystem.isFused() end
 ---
 ---Load a file containing Lua code, returning a Lua chunk that can be run.
 ---
+---
+---### NOTE:
+---An error is thrown if the file contains syntax errors.
+---
 ---@param filename string # The file to load.
 ---@return function chunk # The runnable chunk.
 function lovr.filesystem.load(filename) end
 
 ---
----Mounts a directory or `.zip` archive, adding it to the virtual filesystem.  This allows you to read files from it.
+---Mounts a directory or `.zip` archive, adding it to the virtual filesystem.
+---
+---This allows you to read files from it.
+---
+---
+---### NOTE:
+---The `append` option lets you control the priority of the archive's files in the event of naming collisions.
+---
+---This function is not thread safe.
+---
+---Mounting or unmounting an archive while other threads call lovr.filesystem functions is not supported.
 ---
 ---@param path string # The path to mount.
 ---@param mountpoint? string # The path in the virtual filesystem to mount to.
@@ -149,6 +233,10 @@ function lovr.filesystem.newBlob(filename) end
 ---
 ---Read the contents of a file.
 ---
+---
+---### NOTE:
+---If the file does not exist or cannot be read, nil is returned.
+---
 ---@param filename string # The name of the file to read.
 ---@param bytes? number # The number of bytes to read (if -1, all bytes will be read).
 ---@return string contents # The contents of the file.
@@ -158,6 +246,12 @@ function lovr.filesystem.read(filename, bytes) end
 ---
 ---Remove a file or directory in the save directory.
 ---
+---
+---### NOTE:
+---A directory can only be removed if it is empty.
+---
+---To recursively remove a folder, use this function with `lovr.filesystem.getDirectoryItems`.
+---
 ---@param path string # The file or directory to remove.
 ---@return boolean success # Whether the path was removed.
 function lovr.filesystem.remove(path) end
@@ -169,13 +263,25 @@ function lovr.filesystem.remove(path) end
 function lovr.filesystem.setIdentity(identity) end
 
 ---
----Sets the require path.  The require path is a semicolon-separated list of patterns that LÖVR will use to search for files when they are `require`d.  Any question marks in the pattern will be replaced with the module that is being required.  It is similar to Lua\'s `package.path` variable, but the main difference is that the patterns are relative to the save directory and the project directory.
+---Sets the require path.
+---
+---The require path is a semicolon-separated list of patterns that LÖVR will use to search for files when they are `require`d.
+---
+---Any question marks in the pattern will be replaced with the module that is being required.
+---
+---It is similar to Lua\'s `package.path` variable, but the main difference is that the patterns are relative to the save directory and the project directory.
+---
+---
+---### NOTE:
+---The default reqiure path is '?.lua;?/init.lua'.
 ---
 ---@param path? string # An optional semicolon separated list of search patterns.
 function lovr.filesystem.setRequirePath(path) end
 
 ---
----Sets the location of the project's source.  This can only be done once, and is usually done internally.
+---Sets the location of the project's source.
+---
+---This can only be done once, and is usually done internally.
 ---
 ---@param identity string # The path containing the project's source.
 function lovr.filesystem.setSource(identity) end
@@ -183,6 +289,12 @@ function lovr.filesystem.setSource(identity) end
 ---
 ---Unmounts a directory or archive previously mounted with `lovr.filesystem.mount`.
 ---
+---
+---### NOTE:
+---This function is not thread safe.
+---
+---Mounting or unmounting an archive while other threads call lovr.filesystem functions is not supported.
+---
 ---@param path string # The path to unmount.
 ---@return boolean success # Whether the archive was unmounted.
 function lovr.filesystem.unmount(path) end
@@ -190,6 +302,12 @@ function lovr.filesystem.unmount(path) end
 ---
 ---Write to a file.
 ---
+---
+---### NOTE:
+---If the file does not exist, it is created.
+---
+---If the file already has data in it, it will be replaced with the new content.
+---
 ---@overload fun(filename: string, blob: lovr.Blob):number
 ---@param filename string # The file to write to.
 ---@param content string # A string to write to the file.