improve fs docs and minor blunders

lfs.c

@@ -23,12 +23,15 @@
 #include "util.h"
 
 /***
- * Returns the last component of the given pathname,
+ * Returns the last component of the given path,
  * removing any trailing '/' characters. If the given
  * path consists entirely of '/' characters, the string
  * `"/"` is returned. If *path* is an empty string,
  * the string `"."` is returned.
  *
+ * This is purely a string manipulation function and
+ * depends on no outside state.
+ *
  * @function basename
  * @usage
 print("name of script file is " .. fs.basename(arg[0]))
@@ -70,7 +73,8 @@ static int
 fs_copy(lua_State *L)
 {
 	struct stat sb;
-	const char *source, *target;
+	const char *source; /* parameter 1 (string) */
+	const char *target; /* parameter 2 (string) */
 	char readbuf[512];
 	ssize_t ret;
 	int sfd, tfd;
@@ -118,13 +122,16 @@ finish:
 }
 
 /***
- * Returns the parent directory of the pathname
+ * Returns the parent directory of the pathn
  * given. Any trailing '/' characters are not
  * counted as part of the directory name.
  * If the given path is an empty string or contains
  * no '/' characters, the string `"."` is returned,
  * signifying the current directory.
  *
+ * This is purely a string manipulation function and
+ * depends on no outside state.
+ *
  * @function dirname
  * @usage assert(fs.dirname("/usr/local/bin") == "/usr/local")
  * @tparam string path The path to process.
@@ -149,7 +156,7 @@ fs_dirname(lua_State *L)
 
 /***
  * Returns true if the given pathname exists
- * in the file system, or false if it does not.
+ * in the file system.
  *
  * @function exists
  * @usage
@@ -161,7 +168,7 @@ end
 static int
 fs_exists(lua_State *L)
 {
-	const char *path;
+	const char *path; /* parameter 1 (string) */
 	int ret;
 
 	path = luaL_checkstring(L, 1);
@@ -178,7 +185,7 @@ static int
 ismode(lua_State *L, mode_t mode)
 {
 	struct stat sb;
-	const char *path;
+	const char *path; /* parameter 1 (string) */
 
 	path = luaL_checkstring(L, 1);
 
@@ -199,10 +206,9 @@ ismode(lua_State *L, mode_t mode)
 }
 
 /***
- * Returns true if the given path specifies a
+ * Returns true if the given path specifies a directory.
- * directory, or false if it does not.
+ * Will return false if either the given path does not
- * Will return false if the given path does not
+ * specify a directory or the path does not exist at all.
- * specify an existing directory entry at all.
  *
  * On error returns nil, an error message and a
  * platform-dependent error code.
@@ -221,10 +227,10 @@ fs_isdirectory(lua_State *L)
 }
 
 /***
- * Returns true if the given path specifies a file,
+ * Returns true if the given path specifies a file.
- * or false if it does not.
+ * Will return false if either the given path
- * Will return false if the given path does not
+ * does not specify a directory or the path
- * specify an existing directory entry at all.
+ * does not exist at all.
  *
  * On error returns nil, an error message and a
  * platform-dependent error code.
@@ -296,7 +302,8 @@ mkpath(char *path, mode_t mode, mode_t dir_mode)
  * Creates a new directory.
  *
  * If *recursive* is true, creates intermediate directories
- * as required; behaves as POSIX `mkdir -p` would.
+ * (parent directories) as required; behaves as POSIX
+ * `mkdir -p` would.
  *
  * On success, returns true. Otherwise returns nil, an error
  * message and a platform-dependent error code.
@@ -304,8 +311,7 @@ mkpath(char *path, mode_t mode, mode_t dir_mode)
  * @function mkdir
  * @usage fs.mkdir("/usr/local/bin")
  * @tparam string dir The path of the directory to create.
- * @tparam[opt] boolean recursive Whether to create intermediate
+ * @tparam[opt] boolean recursive Whether to create intermediate directories.
- * directories as required.
  */
 static int
 fs_mkdir(lua_State *L)
@@ -334,11 +340,13 @@ fs_mkdir(lua_State *L)
 }
 
 /***
- * Moves the file at the path *src* to the path *dest*,
+ * Moves the item at path *src* to path *dest*.
- * moving it between directories if required. If *dest*
+ * If *dest* exists, it is overwritten. Both *src* and *dest*
- * exists, it is first removed. Both *src* and *dest*
+ * must be of the same type (that is, both directories or both
- * must be of the same type (that is, both directories or
+ * non-directories) and must reside on the same file system.
- * both non-directories) and must reside on the same file system.
+ *
+ * (If you need to move files across different file systems,
+ * consider using `fs.copy` instead.)
  *
  * On success, returns true. Otherwise returns nil, an error
  * message and a platform-dependent error code.
@@ -365,8 +373,6 @@ fs_move(lua_State *L)
 	}
 
 	return lfail(L);
-
-	return 0;
 }
 
 /***
@@ -382,7 +388,7 @@ fs_move(lua_State *L)
 static int
 fs_rmdir(lua_State *L)
 {
-	const char *dir;
+	const char *dir; /* parameter 1 (string) */
 	int ret;
 
 	dir = luaL_checkstring(L, 1);
@@ -394,8 +400,6 @@ fs_rmdir(lua_State *L)
 	}
 
 	return lfail(L);
-
-	return 0;
 }
 
 /***
@@ -421,22 +425,20 @@ static int
 fs_workdir(lua_State *L)
 {
 	const char *workdir; /* parameter 1 (string) */
-	char *buffer;        /* buffer used by getcwd() */
+	char buffer[512];    /* buffer used by getcwd() */
 	char *ret;
 
 	if (lua_isnoneornil(L, 1)) { /* if first argument was not given... */
-		buffer = malloc(sizeof(char *) * 512);
 		ret = getcwd(buffer, 512);
 
 		if (ret != NULL) {
 			lua_pushstring(L, buffer);
-			free(buffer);
 			return 1;
 		}
 
-		free(buffer);
 		return lfail(L);
-	} else {
+	}
+
 	workdir = luaL_checkstring(L, 1);
 
 	if (chdir(workdir) == 0) {
@@ -445,7 +447,6 @@ fs_workdir(lua_State *L)
 	}
 
 	return lfail(L);
-	}
 }
 
 static const luaL_Reg fslib[] = {