Browse Source

filesystem docs;

bjorn 5 years ago
parent
commit
dd4da17101

+ 31 - 22
api/init.lua

@@ -3947,7 +3947,7 @@ return {
         {
         {
           name = "append",
           name = "append",
           summary = "Append content to the end of a file.",
           summary = "Append content to the end of a file.",
-          description = "Appends content to the end of the file.",
+          description = "Appends content to the end of a file.",
           key = "lovr.filesystem.append",
           key = "lovr.filesystem.append",
           module = "lovr.filesystem",
           module = "lovr.filesystem",
           notes = "If the file does not exist, it is created.",
           notes = "If the file does not exist, it is created.",
@@ -3969,7 +3969,7 @@ return {
                 {
                 {
                   name = "bytes",
                   name = "bytes",
                   type = "number",
                   type = "number",
-                  description = "The number of bytes written."
+                  description = "The number of bytes actually written to the file."
                 }
                 }
               }
               }
             }
             }
@@ -3978,7 +3978,7 @@ return {
         {
         {
           name = "createDirectory",
           name = "createDirectory",
           summary = "Create a directory.",
           summary = "Create a directory.",
-          description = "Creates a directory in the save directory.",
+          description = "Creates a directory in the save directory.  Any parent directories that don't exist will also be created.",
           key = "lovr.filesystem.createDirectory",
           key = "lovr.filesystem.createDirectory",
           module = "lovr.filesystem",
           module = "lovr.filesystem",
           variants = {
           variants = {
@@ -3987,7 +3987,7 @@ return {
                 {
                 {
                   name = "path",
                   name = "path",
                   type = "string",
                   type = "string",
-                  description = "The directory to create."
+                  description = "The directory to create, recursively."
                 }
                 }
               },
               },
               returns = {
               returns = {
@@ -4003,7 +4003,7 @@ return {
         {
         {
           name = "getAppdataDirectory",
           name = "getAppdataDirectory",
           summary = "Get the application data directory.",
           summary = "Get the application data directory.",
-          description = "Returns the application data directory.  This will be something like `C:\\Users\\user\\AppData` on Windows, or `/Users/user/Library/Application Support` on macOS.",
+          description = "Returns the application data directory.  This will be something like:\n\n- `C:\\Users\\user\\AppData\\Roaming` on Windows.\n- `/home/user/.config` on Linux.\n- `/Users/user/Library/Application Support` on macOS.",
           key = "lovr.filesystem.getAppdataDirectory",
           key = "lovr.filesystem.getAppdataDirectory",
           module = "lovr.filesystem",
           module = "lovr.filesystem",
           variants = {
           variants = {
@@ -4022,7 +4022,7 @@ return {
         {
         {
           name = "getApplicationId",
           name = "getApplicationId",
           summary = "Get the application ID.",
           summary = "Get the application ID.",
-          description = "Returns the platform-specific application ID, or `nil` if this does not apply.\n\nCurrently only implemented on Android.",
+          description = "Returns the platform-specific application ID, or `nil` if the current platform doesn't have one.\n\nCurrently only implemented on Android, where it returns the package name, e.g. `org.lovr.app`.",
           key = "lovr.filesystem.getApplicationId",
           key = "lovr.filesystem.getApplicationId",
           module = "lovr.filesystem",
           module = "lovr.filesystem",
           variants = {
           variants = {
@@ -4040,8 +4040,8 @@ return {
         },
         },
         {
         {
           name = "getDirectoryItems",
           name = "getDirectoryItems",
-          summary = "Get a list of files in a directory..",
-          description = "Returns an unsorted table containing all files and subfolders in a directory.",
+          summary = "Get a list of files in a directory.",
+          description = "Returns an unsorted table containing all files and folders in a single directory.",
           key = "lovr.filesystem.getDirectoryItems",
           key = "lovr.filesystem.getDirectoryItems",
           module = "lovr.filesystem",
           module = "lovr.filesystem",
           variants = {
           variants = {
@@ -4076,7 +4076,7 @@ return {
                 {
                 {
                   name = "path",
                   name = "path",
                   type = "string",
                   type = "string",
-                  description = "The absolute path of the LÖVR executable."
+                  description = "The absolute path of the LÖVR executable, or `nil` if it is unknown."
                 }
                 }
               }
               }
             }
             }
@@ -4095,7 +4095,7 @@ return {
                 {
                 {
                   name = "identity",
                   name = "identity",
                   type = "string",
                   type = "string",
-                  description = "The name of the save directory."
+                  description = "The name of the save directory, or `nil` if it isn't set."
                 }
                 }
               }
               }
             }
             }
@@ -4104,23 +4104,23 @@ return {
         {
         {
           name = "getLastModified",
           name = "getLastModified",
           summary = "Get the modification time of a file.",
           summary = "Get the modification time of a file.",
-          description = "Returns when a file was last modified.",
+          description = "Returns when a file was last modified, since some arbitrary time in the past.",
           key = "lovr.filesystem.getLastModified",
           key = "lovr.filesystem.getLastModified",
           module = "lovr.filesystem",
           module = "lovr.filesystem",
           variants = {
           variants = {
             {
             {
               arguments = {
               arguments = {
                 {
                 {
-                  name = "file",
+                  name = "path",
                   type = "string",
                   type = "string",
-                  description = "The file."
+                  description = "The file to check."
                 }
                 }
               },
               },
               returns = {
               returns = {
                 {
                 {
                   name = "time",
                   name = "time",
                   type = "number",
                   type = "number",
-                  description = "The time when the file was last modified, in seconds."
+                  description = "The modification time of the file, in seconds, or `nil` if it's unknown."
                 }
                 }
               }
               }
             }
             }
@@ -4154,7 +4154,7 @@ return {
         {
         {
           name = "getRequirePath",
           name = "getRequirePath",
           summary = "Get the require path.",
           summary = "Get the require path.",
-          description = "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 save directory and the project directory.\n\nFor the C require path, double question marks will be replaced by the name of the module with the operating system's native extension for shared libraries.  For example, if you do `require('lib')` and the C require path is `??`, LÖVR will try to load `lib.dll` if you're on Windows or `lib.so` if you're on Linux.",
+          description = "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.\n\nFor the C require path, double question marks will be replaced by the name of the module with the operating system's native extension for shared libraries.  For example, if you do `require('lib')` and the C require path is `??`, LÖVR will try to load `lib.dll` if you're on Windows or `lib.so` if you're on Linux.",
           key = "lovr.filesystem.getRequirePath",
           key = "lovr.filesystem.getRequirePath",
           module = "lovr.filesystem",
           module = "lovr.filesystem",
           notes = "The default reqiure path is '?.lua;?/init.lua;lua_modules/?.lua;lua_modules/?/init.lua'.  The default C require path is '??'.",
           notes = "The default reqiure path is '?.lua;?/init.lua;lua_modules/?.lua;lua_modules/?/init.lua'.  The default C require path is '??'.",
@@ -4182,6 +4182,10 @@ return {
           description = "Returns the absolute path to the save directory.",
           description = "Returns the absolute path to the save directory.",
           key = "lovr.filesystem.getSaveDirectory",
           key = "lovr.filesystem.getSaveDirectory",
           module = "lovr.filesystem",
           module = "lovr.filesystem",
+          related = {
+            "lovr.filesystem.getIdentity",
+            "lovr.filesystem.getAppdataDirectory"
+          },
           variants = {
           variants = {
             {
             {
               arguments = {},
               arguments = {},
@@ -4201,6 +4205,7 @@ return {
           description = "Returns the size of a file, in bytes.",
           description = "Returns the size of a file, in bytes.",
           key = "lovr.filesystem.getSize",
           key = "lovr.filesystem.getSize",
           module = "lovr.filesystem",
           module = "lovr.filesystem",
+          notes = "If the file does not exist, an error is thrown.",
           variants = {
           variants = {
             {
             {
               arguments = {
               arguments = {
@@ -4233,7 +4238,7 @@ return {
                 {
                 {
                   name = "path",
                   name = "path",
                   type = "string",
                   type = "string",
-                  description = "The absolute path of the project's source."
+                  description = "The absolute path of the project's source, or `nil` if it's unknown."
                 }
                 }
               }
               }
             }
             }
@@ -4271,7 +4276,7 @@ return {
                 {
                 {
                   name = "path",
                   name = "path",
                   type = "string",
                   type = "string",
-                  description = "The current working directory."
+                  description = "The current working directory, or `nil` if it's unknown."
                 }
                 }
               }
               }
             }
             }
@@ -4299,7 +4304,7 @@ return {
                 {
                 {
                   name = "isDirectory",
                   name = "isDirectory",
                   type = "boolean",
                   type = "boolean",
-                  description = "Whether or not path is a directory."
+                  description = "Whether or not the path is a directory."
                 }
                 }
               }
               }
             }
             }
@@ -4327,7 +4332,7 @@ return {
                 {
                 {
                   name = "isFile",
                   name = "isFile",
                   type = "boolean",
                   type = "boolean",
-                  description = "Whether or not path is a file."
+                  description = "Whether or not the path is a file."
                 }
                 }
               }
               }
             }
             }
@@ -4528,7 +4533,7 @@ return {
                 {
                 {
                   name = "path",
                   name = "path",
                   type = "string",
                   type = "string",
-                  description = "The file or folder to remove.."
+                  description = "The file or directory to remove."
                 }
                 }
               },
               },
               returns = {
               returns = {
@@ -4640,7 +4645,10 @@ return {
           description = "Write to a file.",
           description = "Write to a file.",
           key = "lovr.filesystem.write",
           key = "lovr.filesystem.write",
           module = "lovr.filesystem",
           module = "lovr.filesystem",
-          notes = "If the file does not exist, it is created.",
+          related = {
+            "lovr.filesystem.append",
+            "lovr.filesystem.read"
+          },
           variants = {
           variants = {
             {
             {
               arguments = {
               arguments = {
@@ -4663,7 +4671,8 @@ return {
                 }
                 }
               }
               }
             }
             }
-          }
+          },
+          notes = "If the file does not exist, it is created.\n\nIf the file already has data in it, it will be replaced with the new content."
         }
         }
       },
       },
       objects = {}
       objects = {}

+ 2 - 2
api/lovr/filesystem/append.lua

@@ -1,6 +1,6 @@
 return {
 return {
   summary = 'Append content to the end of a file.',
   summary = 'Append content to the end of a file.',
-  description = 'Appends content to the end of the file.',
+  description = 'Appends content to the end of a file.',
   arguments = {
   arguments = {
     {
     {
       name = 'filename',
       name = 'filename',
@@ -17,7 +17,7 @@ return {
     {
     {
       name = 'bytes',
       name = 'bytes',
       type = 'number',
       type = 'number',
-      description = 'The number of bytes written.'
+      description = 'The number of bytes actually written to the file.'
     }
     }
   },
   },
   notes = 'If the file does not exist, it is created.'
   notes = 'If the file does not exist, it is created.'

+ 5 - 2
api/lovr/filesystem/createDirectory.lua

@@ -1,11 +1,14 @@
 return {
 return {
   summary = 'Create a directory.',
   summary = 'Create a directory.',
-  description = 'Creates a directory in the save directory.',
+  description = [[
+    Creates a directory in the save directory.  Any parent directories that don't exist will also be
+    created.
+  ]],
   arguments = {
   arguments = {
     {
     {
       name = 'path',
       name = 'path',
       type = 'string',
       type = 'string',
-      description = 'The directory to create.'
+      description = 'The directory to create, recursively.'
     }
     }
   },
   },
   returns = {
   returns = {

+ 5 - 2
api/lovr/filesystem/getAppdataDirectory.lua

@@ -1,8 +1,11 @@
 return {
 return {
   summary = 'Get the application data directory.',
   summary = 'Get the application data directory.',
   description = [[
   description = [[
-    Returns the application data directory.  This will be something like `C:\Users\user\AppData` on
-    Windows, or `/Users/user/Library/Application Support` on macOS.
+    Returns the application data directory.  This will be something like:
+
+    - `C:\Users\user\AppData\Roaming` on Windows.
+    - `/home/user/.config` on Linux.
+    - `/Users/user/Library/Application Support` on macOS.
   ]],
   ]],
   arguments = {},
   arguments = {},
   returns = {
   returns = {

+ 2 - 2
api/lovr/filesystem/getApplicationId.lua

@@ -1,9 +1,9 @@
 return {
 return {
   summary = 'Get the application ID.',
   summary = 'Get the application ID.',
   description = [[
   description = [[
-    Returns the platform-specific application ID, or `nil` if this does not apply.
+    Returns the platform-specific application ID, or `nil` if the current platform doesn't have one.
 
 
-    Currently only implemented on Android.
+    Currently only implemented on Android, where it returns the package name, e.g. `org.lovr.app`.
   ]],
   ]],
   arguments = {},
   arguments = {},
   returns = {
   returns = {

+ 2 - 2
api/lovr/filesystem/getDirectoryItems.lua

@@ -1,6 +1,6 @@
 return {
 return {
-  summary = 'Get a list of files in a directory..',
-  description = 'Returns an unsorted table containing all files and subfolders in a directory.',
+  summary = 'Get a list of files in a directory.',
+  description = 'Returns an unsorted table containing all files and folders in a single directory.',
   arguments = {
   arguments = {
     {
     {
       name = 'path',
       name = 'path',

+ 1 - 1
api/lovr/filesystem/getExecutablePath.lua

@@ -6,7 +6,7 @@ return {
     {
     {
       name = 'path',
       name = 'path',
       type = 'string',
       type = 'string',
-      description = 'The absolute path of the LÖVR executable.'
+      description = 'The absolute path of the LÖVR executable, or `nil` if it is unknown.'
     }
     }
   }
   }
 }
 }

+ 1 - 1
api/lovr/filesystem/getIdentity.lua

@@ -9,7 +9,7 @@ return {
     {
     {
       name = 'identity',
       name = 'identity',
       type = 'string',
       type = 'string',
-      description = 'The name of the save directory.'
+      description = 'The name of the save directory, or `nil` if it isn\'t set.'
     }
     }
   }
   }
 }
 }

+ 4 - 4
api/lovr/filesystem/getLastModified.lua

@@ -1,18 +1,18 @@
 return {
 return {
   summary = 'Get the modification time of a file.',
   summary = 'Get the modification time of a file.',
-  description = 'Returns when a file was last modified.',
+  description = 'Returns when a file was last modified, since some arbitrary time in the past.',
   arguments = {
   arguments = {
     {
     {
-      name = 'file',
+      name = 'path',
       type = 'string',
       type = 'string',
-      description = 'The file.'
+      description = 'The file to check.'
     }
     }
   },
   },
   returns = {
   returns = {
     {
     {
       name = 'time',
       name = 'time',
       type = 'number',
       type = 'number',
-      description = 'The time when the file was last modified, in seconds.'
+      description = 'The modification time of the file, in seconds, or `nil` if it\'s unknown.'
     }
     }
   }
   }
 }
 }

+ 1 - 2
api/lovr/filesystem/getRequirePath.lua

@@ -4,8 +4,7 @@ return {
     Returns the require path.  The require path is a semicolon-separated list of patterns that LÖVR
     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
     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`
     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.
+    variable, but the main difference is that the patterns are relative to the virtual filesystem.
 
 
     For the C require path, double question marks will be replaced by the name of the module with
     For the C require path, double question marks will be replaced by the name of the module with
     the operating system's native extension for shared libraries.  For example, if you do
     the operating system's native extension for shared libraries.  For example, if you do

+ 4 - 0
api/lovr/filesystem/getSaveDirectory.lua

@@ -8,5 +8,9 @@ return {
       type = 'string',
       type = 'string',
       description = 'The absolute path to the save directory.'
       description = 'The absolute path to the save directory.'
     }
     }
+  },
+  related = {
+    'lovr.filesystem.getIdentity',
+    'lovr.filesystem.getAppdataDirectory'
   }
   }
 }
 }

+ 2 - 1
api/lovr/filesystem/getSize.lua

@@ -14,5 +14,6 @@ return {
       type = 'number',
       type = 'number',
       description = 'The size of the file, in bytes.'
       description = 'The size of the file, in bytes.'
     }
     }
-  }
+  },
+  notes = 'If the file does not exist, an error is thrown.'
 }
 }

+ 1 - 1
api/lovr/filesystem/getSource.lua

@@ -6,7 +6,7 @@ return {
     {
     {
       name = 'path',
       name = 'path',
       type = 'string',
       type = 'string',
-      description = 'The absolute path of the project\'s source.'
+      description = 'The absolute path of the project\'s source, or `nil` if it\'s unknown.'
     }
     }
   }
   }
 }
 }

+ 1 - 1
api/lovr/filesystem/getWorkingDirectory.lua

@@ -9,7 +9,7 @@ return {
     {
     {
       name = 'path',
       name = 'path',
       type = 'string',
       type = 'string',
-      description = 'The current working directory.'
+      description = 'The current working directory, or `nil` if it\'s unknown.'
     }
     }
   }
   }
 }
 }

+ 1 - 1
api/lovr/filesystem/isDirectory.lua

@@ -12,7 +12,7 @@ return {
     {
     {
       name = 'isDirectory',
       name = 'isDirectory',
       type = 'boolean',
       type = 'boolean',
-      description = 'Whether or not path is a directory.'
+      description = 'Whether or not the path is a directory.'
     }
     }
   },
   },
   related = {
   related = {

+ 1 - 1
api/lovr/filesystem/isFile.lua

@@ -12,7 +12,7 @@ return {
     {
     {
       name = 'isFile',
       name = 'isFile',
       type = 'boolean',
       type = 'boolean',
-      description = 'Whether or not path is a file.'
+      description = 'Whether or not the path is a file.'
     }
     }
   },
   },
   related = {
   related = {

+ 1 - 1
api/lovr/filesystem/remove.lua

@@ -5,7 +5,7 @@ return {
     {
     {
       name = 'path',
       name = 'path',
       type = 'string',
       type = 'string',
-      description = 'The file or folder to remove..'
+      description = 'The file or directory to remove.'
     }
     }
   },
   },
   returns = {
   returns = {

+ 9 - 1
api/lovr/filesystem/write.lua

@@ -20,5 +20,13 @@ return {
       description = 'The number of bytes written.'
       description = 'The number of bytes written.'
     }
     }
   },
   },
-  notes = 'If the file does not exist, it is created.'
+  notes = [[
+    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.
+  ]],
+  related = {
+    'lovr.filesystem.append',
+    'lovr.filesystem.read'
+  }
 }
 }