Standardizing the return values in case of error

doc/us/manual.html

@@ -85,12 +85,15 @@ The compiled binary should be copied to a directory in your
 
 <h2><a name="reference"></a>Reference</h2>
 
-<p>LuaFileSystem offers the following functions:</p>
+<p>
+LuaFileSystem offers the following functions:
+</p>
 
 <dl class="reference">
     <dt><a name="attributes"></a><strong><code>lfs.attributes (filepath [, aname])</code></strong></dt>
     <dd>Returns a table with the file attributes corresponding to
-    <code>filepath</code>.
+    <code>filepath</code> (or <code>nil</code> followed by an error message
+    in case of error).
     If the second optional argument is given, then only the value of the
     named attribute is returned (this use is equivalent to
     <code>lfs.attributes(filepath).aname</code>, but the table is not created
@@ -155,8 +158,12 @@ The compiled binary should be copied to a directory in your
     plus an error string.</dd>
     
     <dt><a name="dir"></a><strong><code>lfs.dir (path)</code></strong></dt>
-    <dd>Lua iterator over the entries of a given directory. Raises an
+    <dd>
-    error if <code>path</code> is not a directory.</dd>
+    Lua iterator over the entries of a given directory.
+    Each time the iterator is called it returns a string with an entry of the
+    directory; <code>nil</code> is returned when there is no more entries.
+    Raises an error if <code>path</code> is not a directory.
+    </dd>
     
     <dt><a name="lock"></a><strong><code>lfs.lock (filehandle, mode[, start[, length]])</code></strong></dt>
     <dd>Locks a file or a part of it. This function works on <em>open files</em>; the
@@ -166,20 +173,21 @@ The compiled binary should be copied to a directory in your
     write/exclusive lock). The optional arguments <code>start</code>
     and <code>length</code> can be used to specify a starting point and
     its length; both should be numbers.<br />
-    Returns a boolean indicating if the operation was successful; in
+    Returns <code>true</code> if the operation was successful; in
-    case of error, it returns <code>false</code> plus an error string.
+    case of error, it returns <code>nil</code> plus an error string.
     </dd>
     
     <dt><a name="mkdir"></a><strong><code>lfs.mkdir (dirname)</code></strong></dt>
     <dd>Creates a new directory. The argument is the name of the new
     directory.<br />
-    Returns a boolean indicating whether the operation succeeds or not
+    Returns <code>true</code> if the operation was successful;
-    (in this case, an error string is returned too).</dd>
+    in case of error, it returns <code>nil</code> plus an error string.
+    </dd>
     
     <dt><a name="rmdir"></a><strong><code>lfs.rmdir (dirname)</code></strong></dt>
     <dd>Removes an existing directory. The argument is the name of the directory.<br />
-    Returns a boolean indicating whether the operation succeeds or not
+    Returns <code>true</code> if the operation was successful;
-    (in this case, an error string is returned too).</dd>
+    in case of error, it returns <code>nil</code> plus an error string.</dd>
     
     <dt><a name="touch"></a><strong><code>lfs.touch (filepath [, atime [, mtime]])</code></strong></dt>
     <dd>Set access and modification times of a file. This function is
@@ -188,10 +196,11 @@ The compiled binary should be copied to a directory in your
     and the third argument (<code>mtime</code>) is the modification time.
     Both times are provided in seconds (which should be generated with
     Lua standard function <code>os.date</code>).
-    If the modifition time is omitted, the access time provided is used;
+    If the modification time is omitted, the access time provided is used;
     if both times are omitted, the current time is used.<br />
-    Returns a boolean indicating whether the operation succeeded or not
+    Returns <code>true</code> if the operation was successful;
-    (followed by an error string when it fails).</dd>
+    in case of error, it returns <code>nil</code> plus an error string.
+    </dd>
     
     <dt><a name="unlock"></a><strong><code>lfs.unlock (filehandle[, start[, length]])</code></strong></dt>
     <dd>Unlocks a file or a part of it. This function works on
@@ -199,9 +208,9 @@ The compiled binary should be copied to a directory in your
     argument. The optional arguments <code>start</code> and
     <code>length</code> can be used to specify a starting point and its
     length; both should be numbers.<br />
-    Returns a boolean indicating if the operation was successful; in
+    Returns <code>true</code> if the operation was successful;
-    case of error, it returns <code>false</code> plus a string
+    in case of error, it returns <code>nil</code> plus an error string.
-    describing the error.</dd>
+    </dd>
 </dl>
 
 </div> <!-- id="content" -->
@@ -211,7 +220,7 @@ The compiled binary should be copied to a directory in your
 <div id="about">
 	<p><a href="http://validator.w3.org/check?uri=referer">
     <img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
-	<p><small>$Id: manual.html,v 1.28 2006/03/14 13:16:18 tomas Exp $</small></p>
+	<p><small>$Id: manual.html,v 1.29 2006/03/14 15:03:34 tomas Exp $</small></p>
 </div> <!-- id="about" -->
 
 </div> <!-- id="container" -->