ssh: The ssh_sftp documentation is now generated

3 files changed, 485 insertions, 291 deletions

diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml
index c89092798d..76d2b21946 100644
--- a/lib/ssh/doc/src/ssh_sftp.xml
+++ b/lib/ssh/doc/src/ssh_sftp.xml
@@ -37,60 +37,106 @@
     SSH.</p>
   </description>
   
- <section>
-    <title>DATA TYPES</title>
-    <p>Type definitions that are used more than once in this module,
-    or abstractions to indicate the intended use of the data type, or both:
-    </p>
-
-    <taglist>
-      <tag><c>reason()</c></tag>
-      <item>
-	<p>= <c>atom() | string() | tuple() </c>A description of the reason why an operation failed.</p>
-	<p>
-	  The <c>atom()</c> value is formed from the sftp error codes in the protocol-level responses as defined in 
-	  <url href="https://tools.ietf.org/id/draft-ietf-secsh-filexfer-13.txt">draft-ietf-secsh-filexfer-13.txt</url>
-	  section 9.1.
-	</p>
-	<p>
+  <datatypes>
+    <datatype_title>Error cause</datatype_title>
+    <datatype>
+      <name name="reason"/>
+      <desc>
+	<p>A description of the reason why an operation failed.</p>
+	<p>The <c>atom()</c> value is formed from the sftp error codes in the protocol-level responses as defined in 
+	<url href="https://tools.ietf.org/html/draft-ietf-secsh-filexfer-13#page-49">draft-ietf-secsh-filexfer-13</url>
+	section 9.1.
 	  The codes are named as <c>SSH_FX_*</c> which are transformed into lowercase of the star-part.
 	  E.g. the error code <c>SSH_FX_NO_SUCH_FILE</c>
 	  will cause the <c>reason()</c> to be <c>no_such_file</c>.
 	</p>
 	<p>The <c>string()</c> reason is the error information from the server in case of an exit-signal.  If that information is empty, the reason is the exit signal name.
 	</p>
-	<p>The <c>tuple()</c> reason are other errors like the <c>{exit_status,integer()}</c> if the exit status is not 0.
+	<p>The <c>tuple()</c> reason are other errors like for example <c>{exit_status,1}</c>.
+	</p>
+      </desc>
+    </datatype>
+
+    <datatype_title>Crypto operations for open_tar</datatype_title>
+    <datatype>
+      <name name="tar_crypto_spec"/>
+      <name name="encrypt_spec"/>
+      <name name="decrypt_spec"/>
+      <desc>
+	<p>Specifies the encryption or decryption applied to tar files when using
+	<seealso marker="#open_tar/3">open_tar/3</seealso> or 
+	<seealso marker="#open_tar/4">open_tar/4</seealso>.
+	</p>
+	<p>The encryption or decryption is applied to the generated stream of
+	bytes prior to sending the resulting stream to the SFTP server.
+	</p>
+	<p>For code examples see Section
+	<seealso marker="using_ssh#example-with-encryption">Example with encryption</seealso>
+	in the ssh Users Guide.
 	</p>
-      </item>
+      </desc>
+    </datatype>
 
-      <tag><c>connection_ref() =</c></tag>
-      <item><p><c>opaque()</c> - as returned by 
-      <seealso marker="ssh#connect-3"><c>ssh:connect/3</c></seealso></p></item>
+    <datatype>
+      <name name="init_fun"/>
+      <name name="chunk_size"/>
+      <name name="crypto_state"/>
+      <desc>
+	<p>The <c>init_fun()</c> in the
+	<seealso marker="#type-tar_crypto_spec">tar_crypto_spec</seealso>
+	is applied once prior to any other <c>crypto</c>
+	operation. The intention is that this function initiates the encryption or
+	decryption for example by calling
+	<seealso marker="crypto:crypto#crypto_init/4">crypto:crypto_init/4</seealso>
+	or similar. The <c>crypto_state()</c> is the state such a function may return.
+	</p>
+	<p>If the selected cipher needs to have the input data partioned into
+	blocks of a certain size, the <c>init_fun()</c> should return the second
+	form of return value with the <c>chunk_size()</c> set to the block size.
+	If the <c>chunk_size()</c> is <c>undefined</c>, the size of the <c>PlainBin</c>s varies,
+	because this is	intended for stream crypto, whereas a fixed <c>chunk_size()</c> is intended for block crypto.
+	A <c>chunk_size()</c> can be changed in the return from the <c>crypto_fun()</c>.
+	The value can be changed between <c>pos_integer()</c> and <c>undefined</c>.
+	</p>
+      </desc>
+    </datatype>
 
-      <tag><c>timeout()</c></tag>
-      <item><p>= <c>infinity | integer()</c> in milliseconds. Default infinity.</p></item>
-    </taglist>
-   </section>
+    <datatype>
+      <name name="crypto_fun"/>
+      <name name="crypto_result"/>
+      <desc>
+	<p>The initial <c>crypto_state()</c> returned from the
+	<seealso marker="#type-init_fun">init_fun()</seealso>
+	is folded into repeated applications of the <c>crypto_fun()</c> in the
+	<seealso marker="#type-tar_crypto_spec">tar_crypto_spec</seealso>.
+	The binary returned from that fun is sent to the remote SFTP server and
+	the new <c>crypto_state()</c> is used in the next call of the
+	<c>crypto_fun()</c>.
+	</p>
+	<p>If the <c>crypto_fun()</c> reurns a <c>chunk_size()</c>, that value
+	is as block size for further blocks in calls to <c>crypto_fun()</c>.
+	</p>
+      </desc>
+    </datatype>
 
- <section>
-    <title>Time-outs</title>
-    <p>If the request functions for the SFTP channel return <c>{error, timeout}</c>,
-     no answer was received from the server within the expected time.</p>
-     <p>The request may have reached the server and may have been performed.
-     However, no answer was received from the server within the expected time.</p>
-   </section>
+    <datatype>
+      <name name="final_fun"/>
+      <desc>
+	<p>If doing encryption,
+	the <c>final_fun()</c>  in the
+	<seealso marker="#type-tar_crypto_spec">tar_crypto_spec</seealso>
+	is applied to the last piece of data.
+	The <c>final_fun()</c> is responsible for padding (if needed) and
+	encryption of that last piece.
+	</p>
+      </desc>
+    </datatype>
+  </datatypes>
 
   <funcs>
      <func>
-       <name since="">apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, reason()}</name>
+       <name name="apread" arity="4" since=""/>
        <fsummary>Reads asynchronously from an open file.</fsummary>
-       <type>
-	 <v>ChannelPid = pid()</v>
-         <v>Handle = term()</v>
-         <v>Position = integer()</v>
-         <v>Len = integer()</v>
-         <v>N = term()</v>
-       </type>
        <desc><p>The <c><![CDATA[apread/4]]></c> function reads from a specified position,
        combining the <seealso marker="#position-3"><c>position/3</c></seealso> and 
        <seealso marker="#aread-3"><c>aread/3</c></seealso> functions.</p>
@@ -98,17 +144,8 @@
      </func>
      
      <func>
-	<name since="">apwrite(ChannelPid, Handle, Position, Data) -> {async, N} | {error, reason()}</name>
+	<name name="apwrite" arity="4" since=""/>
 	<fsummary>Writes asynchronously to an open file.</fsummary>
-	<type>
-	  <v>ChannelPid = pid()</v>
-	  <v>Handle = term()</v>
-	  <v>Position = integer()</v>
-	  <v>Len = integer()</v>
-	  <v>Data = binary()</v>
-	  <v>Timeout = timeout()</v>
-          <v>N = term()</v>
-	</type>
        <desc><p>The <c><![CDATA[apwrite/4]]></c> function writes to a specified position,
        combining the <seealso marker="#position-3"><c>position/3</c></seealso> and 
        <seealso marker="#awrite-3"><c>awrite/3</c></seealso> functions.</p>
@@ -116,15 +153,8 @@
       </func>
       
       <func>
-	<name since="">aread(ChannelPid, Handle, Len) -> {async, N} | {error, reason()}</name>
+	<name name="aread" arity="3" since=""/>
 	<fsummary>Reads asynchronously from an open file.</fsummary>
-	<type>
-	  <v>ChannelPid = pid()</v>
-	  <v>Handle = term()</v>
-	  <v>Position = integer()</v>
-	  <v>Len = integer()</v>
-	  <v>N = term()</v>
-	</type>
 	<desc>
 	  <p>Reads from an open file, without waiting for the result. If the
           handle is valid, the function returns <c><![CDATA[{async, N}]]></c>, where <c>N</c>
@@ -137,16 +167,8 @@
     </func>
 
     <func>
-      <name since="">awrite(ChannelPid, Handle, Data) -> {async, N} | {error, reason()}</name>
+      <name name="awrite" arity="3" since=""/>
       <fsummary>Writes asynchronously to an open file.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Handle = term()</v>
-        <v>Position = integer()</v>
-        <v>Len = integer()</v>
-        <v>Data = binary()</v>
-	<v>Timeout = timeout()</v>
-      </type>
       <desc>
         <p>Writes to an open file, without waiting for the result. If the
           handle is valid, the function returns <c><![CDATA[{async, N}]]></c>, where <c>N</c>
@@ -159,28 +181,18 @@
     </func>
 
     <func>
-      <name since="">close(ChannelPid, Handle) -></name>
-      <name since="">close(ChannelPid, Handle, Timeout) -> ok | {error, reason()}</name>
+      <name name="close" arity="2" since=""/>
+      <name name="close" arity="3" since=""/>
       <fsummary>Closes an open handle.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Handle = term()</v>
-	<v>Timeout = timeout()</v>
-      </type>
       <desc>
         <p>Closes a handle to an open file or directory on the server.</p>
       </desc>
     </func>
 
     <func>
-      <name since="">delete(ChannelPid, Name) -></name>
-      <name since="">delete(ChannelPid, Name, Timeout) -> ok | {error, reason()}</name>
+      <name name="delete" arity="2" since=""/>
+      <name name="delete" arity="3" since=""/>
       <fsummary>Deletes a file.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Name = string()</v>
-	<v>Timeout = timeout()</v>
-      </type>
       <desc>
         <p>Deletes the file specified by <c><![CDATA[Name]]></c>.
 	</p>
@@ -188,14 +200,9 @@
     </func>
 
     <func>
-      <name since="">del_dir(ChannelPid, Name) -></name>
-      <name since="">del_dir(ChannelPid, Name, Timeout) -> ok | {error, reason()}</name>
+      <name name="del_dir" arity="2" since=""/>
+      <name name="del_dir" arity="3" since=""/>
       <fsummary>Deletes an empty directory.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Name = string()</v>
-	<v>Timeout = timeout()</v>
-      </type>
       <desc>
 	<p>Deletes a directory specified by <c><![CDATA[Name]]></c>.
 	The directory must be empty before it can be successfully deleted.
@@ -204,16 +211,9 @@
     </func>
 
      <func>
-      <name since="">list_dir(ChannelPid, Path) -></name>
-      <name since="">list_dir(ChannelPid, Path, Timeout) -> {ok, Filenames} | {error, reason()}</name>
+      <name name="list_dir" arity="2" since=""/>
+      <name name="list_dir" arity="3" since=""/>
       <fsummary>Lists the directory.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Path = string()</v>
-        <v>Filenames = [Filename]</v>
-        <v>Filename = string()</v>
-	<v>Timeout = timeout()</v>
-      </type>
       <desc>
         <p>Lists the given directory on the server, returning the
           filenames as a list of strings.</p>
@@ -221,14 +221,9 @@
     </func>
 
     <func>
-      <name since="">make_dir(ChannelPid, Name) -></name>
-      <name since="">make_dir(ChannelPid, Name, Timeout) -> ok | {error, reason()}</name>
+      <name name="make_dir" arity="2" since=""/>
+      <name name="make_dir" arity="3" since=""/>
       <fsummary>Creates a directory.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Name = string()</v>
-	<v>Timeout = timeout()</v>
-      </type>
       <desc>
         <p>Creates a directory specified by <c><![CDATA[Name]]></c>. <c><![CDATA[Name]]></c>
           must be a full path to a new directory. The directory can only be
@@ -237,14 +232,9 @@
     </func>
 
     <func>
-      <name since="">make_symlink(ChannelPid, Name, Target) -></name>
-      <name since="">make_symlink(ChannelPid, Name, Target, Timeout) -> ok | {error, reason()}</name>
+      <name name="make_symlink" arity="3" since=""/>
+      <name name="make_symlink" arity="4" since=""/>
       <fsummary>Creates a symbolic link.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Name = string()</v>
-        <v>Target = string()</v>
-      </type>
       <desc>
         <p>Creates a symbolic link pointing to <c><![CDATA[Target]]></c> with the
           name <c><![CDATA[Name]]></c>.
@@ -252,32 +242,19 @@
       </desc>
     </func>
 
-       <func>
-      <name since="">open(ChannelPid, File, Mode) -></name>
-      <name since="">open(ChannelPid, File, Mode, Timeout) -> {ok, Handle} | {error, reason()}</name>
+    <func>
+      <name name="open" arity="3" since=""/>
+      <name name="open" arity="4" since=""/>
       <fsummary>Opens a file and returns a handle.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>File = string()</v>
-        <v>Mode = [Modeflag]</v>
-        <v>Modeflag = read | write | creat | trunc | append | binary</v>
-	<v>Timeout = timeout()</v>
-	<v>Handle = term()</v>
-      </type>
       <desc>
         <p>Opens a file on the server and returns a handle, which
           can be used for reading or writing.</p>
       </desc>
     </func>
     <func>
-      <name since="">opendir(ChannelPid, Path) -></name>
-      <name since="">opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | {error, reason()}</name>
+      <name name="opendir" arity="2" since=""/>
+      <name name="opendir" arity="3" since=""/>
       <fsummary>Opens a directory and returns a handle.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Path = string()</v>
-	<v>Timeout = timeout()</v>
-      </type>
       <desc>
         <p>Opens a handle to a directory on the server. The handle
           can be used for reading directory contents.</p>
@@ -285,72 +262,36 @@
     </func>
 
     <func>
-      <name since="OTP 17.4">open_tar(ChannelPid, Path, Mode) -></name>
-      <name since="OTP 17.4">open_tar(ChannelPid, Path, Mode, Timeout) -> {ok, Handle} | {error, reason()}</name>
+      <name name="open_tar" arity="3" since="OTP 17.4"/>
+      <name name="open_tar" arity="4" since="OTP 17.4"/>
       <fsummary>Opens a tar file on the server to which <c>ChannelPid</c>
       is connected and returns a handle.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Path = string()</v>
-	<v>Mode = [read] | [write] | [read,EncryptOpt] | [write,DecryptOpt]</v>
-	<v>EncryptOpt = {crypto,{InitFun,EncryptFun,CloseFun}}</v>
-	<v>DecryptOpt = {crypto,{InitFun,DecryptFun}}</v>
-	<v>InitFun = (fun() -> {ok,CryptoState}) | (fun() -> {ok,CryptoState,ChunkSize})</v>
-	<v>CryptoState = any()</v>
-	<v>ChunkSize = undefined | pos_integer()</v>
-	<v>EncryptFun = (fun(PlainBin,CryptoState) -> EncryptResult)</v>
-	<v>EncryptResult = {ok,EncryptedBin,CryptoState} | {ok,EncryptedBin,CryptoState,ChunkSize}</v>
-	<v>PlainBin = binary()</v>
-	<v>EncryptedBin = binary()</v>
-	<v>DecryptFun = (fun(EncryptedBin,CryptoState) -> DecryptResult)</v>
-	<v>DecryptResult = {ok,PlainBin,CryptoState} | {ok,PlainBin,CryptoState,ChunkSize}</v>
-	<v>CloseFun = (fun(PlainBin,CryptoState) -> {ok,EncryptedBin})</v>
-	<v>Timeout = timeout()</v>
-      </type>
       <desc>
         <p>Opens a handle to a tar file on the server, associated with <c>ChannelPid</c>.
-	The handle can be used for remote tar creation and extraction, as defined by the
-	<seealso marker="stdlib:erl_tar#init-3">erl_tar:init/3</seealso> function.
-	</p>
-
-	<p> For code exampel see Section
-	<seealso marker="using_ssh">SFTP Client with TAR Compression and Encryption</seealso> in
-	the ssh Users Guide. </p>
-
-	<p>The <c>crypto</c> mode option is applied to the generated stream of bytes prior to sending
-	them to the SFTP server. This is intended for encryption but can be used for other
-	purposes.
+	The handle can be used for remote tar creation and extraction. The actual writing
+	and reading is performed by calls to 
+	<seealso marker="stdlib:erl_tar#add-3">erl_tar:add/3,4</seealso> and
+	<seealso marker="stdlib:erl_tar#extract-2">erl_tar:extract/2</seealso>.
+	Note: The 
+	<seealso marker="stdlib:erl_tar#init-3">erl_tar:init/3</seealso> function should not
+	be called, that one is called by this open_tar function.
 	</p>
-	<p>The <c>InitFun</c> is applied once
-	prior to any other <c>crypto</c> operation. The returned <c>CryptoState</c> is then folded into
-	repeated applications of the <c>EncryptFun</c> or <c>DecryptFun</c>. The binary returned
-	from those funs are sent further to the remote SFTP server. Finally, if doing encryption,
-	the <c>CloseFun</c> is applied to the last piece of data. The <c>CloseFun</c> is
-	responsible for padding (if needed) and encryption of that last piece.
+	<p>For code examples see Section
+	<seealso marker="using_ssh#sftp-client-with-tar-compression">SFTP Client with TAR Compression</seealso>
+	in the ssh Users Guide.
 	</p>
-	<p>The <c>ChunkSize</c> defines the size of the <c>PlainBin</c>s that <c>EncodeFun</c> is applied
-	to. If the <c>ChunkSize</c> is <c>undefined</c>, the size of the <c>PlainBin</c>s varies,
-	because this is	intended for stream crypto, whereas a fixed <c>ChunkSize</c> is intended for block crypto.
-	<c>ChunkSize</c>s can be changed in the return from the <c>EncryptFun</c> or
-	<c>DecryptFun</c>. The value can be changed between <c>pos_integer()</c> and <c>undefined</c>.
+	<p>The <c>crypto</c> mode option is explained in the data types section above, see
+	<seealso marker="#Crypto operations for open_tar">Crypto operations for open_tar</seealso>.
+	Encryption is assumed if the <c>Mode</c> contains <c>write</c>, and
+	decryption if the <c>Mode</c> contains <c>read</c>.
 	</p>
-
       </desc>
     </func>
 
     <func>
-      <name since="">position(ChannelPid, Handle, Location) -></name>
-      <name since="">position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition | {error, reason()}</name>
+      <name name="position" arity="3" since=""/>
+      <name name="position" arity="4" since=""/>
       <fsummary>Sets the file position of a file.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Handle = term()</v>
-        <v>Location = Offset
- | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof</v>
-        <v>Offset = integer()</v>
-	<v>Timeout = timeout()</v>
-        <v>NewPosition = integer()</v>
-      </type>
       <desc>
         <p>Sets the file position of the file referenced by <c><![CDATA[Handle]]></c>.
           Returns <c><![CDATA[{ok, NewPosition}]]></c> (as an absolute offset) if
@@ -384,17 +325,9 @@
     </func>
 
     <func>
-      <name since="">pread(ChannelPid, Handle, Position, Len) -></name>
-      <name since="">pread(ChannelPid, Handle, Position, Len, Timeout) -> {ok, Data} | eof | {error, reason()}</name>
+      <name name="pread" arity="4" since=""/>
+      <name name="pread" arity="5" since=""/>
       <fsummary>Reads from an open file.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Handle = term()</v>
-        <v>Position = integer()</v>
-        <v>Len = integer()</v>
-	<v>Timeout = timeout()</v>
-        <v>Data = string() | binary()</v>
-      </type>
        <desc><p>The <c><![CDATA[pread/3,4]]></c> function reads from a specified position,
        combining the <seealso marker="#position-3"><c>position/3</c></seealso> and 
        <seealso marker="#read-3"><c>read/3,4</c></seealso> functions.</p>
@@ -402,16 +335,9 @@
      </func>
 
     <func>
-      <name since="">pwrite(ChannelPid, Handle, Position, Data) -> ok</name>
-      <name since="">pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | {error, reason()}</name>
+      <name name="pwrite" arity="4" since=""/>
+      <name name="pwrite" arity="5" since=""/>
       <fsummary>Writes to an open file.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Handle = term()</v>
-        <v>Position = integer()</v>
-        <v>Data = iolist()</v>
-	<v>Timeout = timeout()</v>
-      </type>
        <desc><p>The <c><![CDATA[pwrite/3,4]]></c> function writes to a specified position,
        combining the <seealso marker="#position-3"><c>position/3</c></seealso> and 
        <seealso marker="#write-3"><c>write/3,4</c></seealso> functions.</p>
@@ -419,16 +345,9 @@
     </func>
 
     <func>
-      <name since="">read(ChannelPid, Handle, Len) -></name>
-      <name since="">read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error, reason()}</name>
+      <name name="read" arity="3" since=""/>
+      <name name="read" arity="4" since=""/>
       <fsummary>Reads from an open file.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Handle = term()</v>
-        <v>Len = integer()</v>
-	<v>Timeout = timeout()</v>
-        <v>Data = string() | binary()</v>
-      </type>
       <desc>
         <p>Reads <c><![CDATA[Len]]></c> bytes from the file referenced by
           <c><![CDATA[Handle]]></c>. Returns <c><![CDATA[{ok, Data}]]></c>, <c><![CDATA[eof]]></c>, or
@@ -440,32 +359,19 @@
       </desc>
     </func>
 
-      <func>
-      <name since="">read_file(ChannelPid, File) -></name>
-      <name since="">read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, reason()}</name>
+    <func>
+      <name name="read_file" arity="2" since=""/>
+      <name name="read_file" arity="3" since=""/>
       <fsummary>Reads a file.</fsummary>
-      <type>
-	<v>ChannelPid = pid()</v>
-	<v>File = string()</v>
-        <v>Data = binary()</v>
-	<v>Timeout = timeout()</v>
-      </type>
       <desc>
         <p>Reads a file from the server, and returns the data in a binary.</p>
       </desc>
     </func>
 
-      <func>
-      <name since="">read_file_info(ChannelPid, Name) -></name>
-      <name since="">read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, reason()}</name>
+    <func>
+      <name name="read_file_info" arity="2" since=""/>
+      <name name="read_file_info" arity="3" since=""/>
       <fsummary>Gets information about a file.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Name = string()</v>
-        <v>Handle = term()</v>
-	<v>Timeout = timeout()</v>
-        <v>FileInfo = record()</v>
-      </type>
       <desc>
         <p>Returns a <c><![CDATA[file_info]]></c> record from the file system object specified by
           <c><![CDATA[Name]]></c> or <c><![CDATA[Handle]]></c>. See
@@ -474,38 +380,26 @@
 	</p>
 	<p>
 	  Depending on the underlying OS:es links might be followed and info on the final file, directory
-	  etc is returned. See <seealso marker="#read_link_info-2">ssh_sftp::read_link_info/2</seealso>
+	  etc is returned. See <seealso marker="#read_link_info-2">read_link_info/2</seealso>
 	  on how to get information on links instead.
 	</p>
       </desc>
     </func>
 
      <func>
-      <name since="">read_link(ChannelPid, Name) -></name>
-      <name since="">read_link(ChannelPid, Name, Timeout) -> {ok, Target} | {error, reason()}</name>
+      <name name="read_link" arity="2" since=""/>
+      <name name="read_link" arity="3" since=""/>
       <fsummary>Reads symbolic link.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Name = string()</v>
-        <v>Target = string()</v>
-      </type>
       <desc>
         <p>Reads the link target from the symbolic link specified by <c><![CDATA[name]]></c>.
 	</p>
       </desc>
     </func>
 
-     <func>
-      <name since="">read_link_info(ChannelPid, Name) -> {ok, FileInfo} | {error, reason()}</name>
-      <name since="">read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, reason()}</name>
+    <func>
+      <name since="" name="read_link_info" arity="2"/>
+      <name since="" name="read_link_info" arity="3"/>
       <fsummary>Gets information about a symbolic link.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Name = string()</v>
-        <v>Handle = term()</v>
-	<v>Timeout = timeout()</v>
-        <v>FileInfo = record()</v>
-      </type>
       <desc>
         <p>Returns a <c><![CDATA[file_info]]></c> record from the symbolic
           link specified by <c><![CDATA[Name]]></c> or <c><![CDATA[Handle]]></c>.
@@ -517,15 +411,9 @@
     </func>
 
     <func>
-      <name since="">rename(ChannelPid, OldName, NewName) -> </name>
-      <name since="">rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, reason()}</name>
+      <name since="" name="rename" arity="3"/>
+      <name since="" name="rename" arity="4"/>
       <fsummary>Renames a file.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>OldName = string()</v>
-        <v>NewName = string()</v>
-	<v>Timeout = timeout()</v>
-      </type>
       <desc>
         <p>Renames a file named <c><![CDATA[OldName]]></c> and gives it the name
           <c><![CDATA[NewName]]></c>.
@@ -594,11 +482,8 @@
     </func>
 
      <func>
-      <name since="">stop_channel(ChannelPid) -> ok</name>
+      <name since="" name="stop_channel" arity="1"/>
       <fsummary>Stops the SFTP client channel.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-      </type>
       <desc>
 	<p>Stops an SFTP channel. Does not close the SSH connection.
 	Use <seealso marker="ssh#close-1">ssh:close/1</seealso> to close it.</p>
@@ -606,16 +491,9 @@
     </func>
 
     <func>
-      <name since="">write(ChannelPid, Handle, Data) -></name>
-      <name since="">write(ChannelPid, Handle, Data, Timeout) -> ok | {error, reason()}</name>
+      <name since="" name="write" arity="3"/>
+      <name since="" name="write" arity="4"/>
       <fsummary>Writes to an open file.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Handle = term()</v>
-        <v>Position = integer()</v>
-        <v>Data = iolist()</v>
-	<v>Timeout = timeout()</v>
-      </type>
       <desc>
         <p>Writes <c><![CDATA[data]]></c> to the file referenced by <c><![CDATA[Handle]]></c>.
 	The file is to be opened with <c><![CDATA[write]]></c> or <c><![CDATA[append]]></c>
@@ -625,15 +503,9 @@
     </func>
     
     <func>
-      <name since="">write_file(ChannelPid, File, Iolist) -></name>
-      <name since="">write_file(ChannelPid, File, Iolist, Timeout) -> ok | {error, reason()}</name>
+      <name since="" name="write_file" arity="3"/>
+      <name since="" name="write_file" arity="4"/>
       <fsummary>Writes a file.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>File = string()</v>
-        <v>Iolist = iolist()</v>
-	<v>Timeout = timeout()</v>
-      </type>
       <desc>
         <p>Writes a file to the server.	The file is created if it does not exist
 	but overwritten if it exists.</p>
@@ -641,15 +513,9 @@
     </func>
     
     <func>
-      <name since="">write_file_info(ChannelPid, Name, Info) -></name>
-      <name since="">write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, reason()}</name>
+      <name since="" name="write_file_info" arity="3"/>
+      <name since="" name="write_file_info" arity="4"/>
       <fsummary>Writes information for a file.</fsummary>
-      <type>
-        <v>ChannelPid = pid()</v>
-        <v>Name = string()</v>
-        <v>Info = record()</v>
-	<v>Timeout = timeout()</v>
-      </type>
       <desc>
         <p>Writes file information from a <c><![CDATA[file_info]]></c> record to the
 	file specified by <c><![CDATA[Name]]></c>. See
diff --git a/lib/ssh/doc/src/using_ssh.xml b/lib/ssh/doc/src/using_ssh.xml
index 4455d5ecc5..5c56dee81d 100644
--- a/lib/ssh/doc/src/using_ssh.xml
+++ b/lib/ssh/doc/src/using_ssh.xml
@@ -232,9 +232,10 @@
   </section>
 
   <section>
-    <title>SFTP Client with TAR Compression and Encryption</title>
-
-    <p>Example of writing and then reading a tar file follows:</p>
+    <title>SFTP Client with TAR Compression</title>
+    <section>
+      <title>Basic example</title>
+    <p>This is an example of writing and then reading a tar file:</p>
     <code type="erl">
       {ok,HandleWrite} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [write]),
       ok = erl_tar:add(HandleWrite, .... ),
@@ -248,8 +249,12 @@
       {ok,NameValueList} = erl_tar:extract(HandleRead,[memory]),
       ok = erl_tar:close(HandleRead),
     </code>
+  </section>
 
-    <p>The previous write and read example can be extended with encryption and decryption as follows:</p>
+  <section>
+    <title>Example with encryption</title>
+    <p>The previous <seealso marker="using_ssh#basic-example">Basic example</seealso>
+    can be extended with encryption and decryption as follows:</p>
     <code type="erl">
 %% First three parameters depending on which crypto type we select:
 Key = &lt;&lt;"This is a 256 bit key. abcdefghi">>,
@@ -297,6 +302,7 @@ Cr = {InitFun,DecryptFun},
 ok = erl_tar:close(HandleRead),
     </code>
   </section>
+  </section>
 
   <section>
     <marker id="usersguide_creating_a_subsystem"/>
diff --git a/lib/ssh/src/ssh_sftp.erl b/lib/ssh/src/ssh_sftp.erl
index 1b2ba5a50b..9162de3487 100644
--- a/lib/ssh/src/ssh_sftp.erl
+++ b/lib/ssh/src/ssh_sftp.erl
@@ -92,16 +92,26 @@
 -define(XF(S), S#state.xf).
 -define(REQID(S), S#state.req_id).
 
+
+-type reason() :: atom() | string() | tuple() .
+
 %%====================================================================
 %% API
 %%====================================================================
 start_channel(Cm) when is_pid(Cm) ->
     start_channel(Cm, []);
+
 start_channel(Socket) when is_port(Socket) ->
     start_channel(Socket, []);
+
 start_channel(Host) when is_list(Host) ->
     start_channel(Host, []).
 
+
+-spec start_channel(ssh:connection_ref() | gen_tcp:socket() | string(),
+                    ssh:client_options()
+                   ) -> {ok,pid()} | {ok,pid(),ssh:connection_ref()} | {error,term()}.
+
 start_channel(Socket, UserOptions) when is_port(Socket) ->
     {SshOpts, _ChanOpts, SftpOpts} = handle_options(UserOptions),
     Timeout =   % A mixture of ssh:connect and ssh_sftp:start_channel:
@@ -144,6 +154,10 @@ start_channel(Cm, UserOptions) when is_pid(Cm) ->
 start_channel(Host, UserOptions) ->
     start_channel(Host, 22, UserOptions).
 
+
+-spec start_channel(string(), integer(), ssh:client_options()) ->
+                           {ok,pid(),ssh:connection_ref()} | {error,term()}.
+
 start_channel(Host, Port, UserOptions) ->
     {SshOpts, ChanOpts, SftpOpts} = handle_options(UserOptions),
     Timeout =   % A mixture of ssh:connect and ssh_sftp:start_channel:
@@ -168,6 +182,10 @@ start_channel(Host, Port, UserOptions) ->
 	    Error
     end.
 
+
+-spec stop_channel(ChannelPid) -> ok when
+      ChannelPid :: pid().
+
 stop_channel(Pid) ->
     case is_process_alive(Pid) of
 	true ->
@@ -188,17 +206,62 @@ stop_channel(Pid) ->
 wait_for_version_negotiation(Pid, Timeout) ->
     call(Pid, wait_for_version_negotiation, Timeout).
 
+-spec open(ChannelPid, Name, Mode) -> {ok, Handle} | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      Mode :: [read | write | append | binary | raw],
+      Handle :: term(),
+      Error :: {error, reason()} .
 open(Pid, File, Mode) ->
     open(Pid, File, Mode, ?FILEOP_TIMEOUT).
+-spec open(ChannelPid, Name, Mode, Timeout) -> {ok, Handle} | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      Mode :: [read | write | append | binary | raw],
+      Timeout :: timeout(),
+      Handle :: term(),
+      Error :: {error, reason()} .
 open(Pid, File, Mode, FileOpTimeout) ->
     call(Pid, {open, false, File, Mode}, FileOpTimeout).
 
+
+-type tar_crypto_spec() :: encrypt_spec() | decrypt_spec() .
+
+-type encrypt_spec() :: {init_fun(), crypto_fun(), final_fun()} .
+-type decrypt_spec() :: {init_fun(), crypto_fun()} .
+
+-type init_fun() :: fun(() -> {ok,crypto_state()})
+                  | fun(() -> {ok,crypto_state(),chunk_size()}) .
+
+-type crypto_fun() :: fun((TextIn::binary(), crypto_state()) -> crypto_result()) .
+-type crypto_result() :: {ok,TextOut::binary(),crypto_state()}
+                       | {ok,TextOut::binary(),crypto_state(),chunk_size()} .
+
+-type final_fun() :: fun((FinalTextIn::binary(),crypto_state()) -> {ok,FinalTextOut::binary()}) .
+
+-type chunk_size() :: undefined | pos_integer().
+-type crypto_state() :: any() .
+
+
+-spec open_tar(ChannelPid, Path, Mode) -> {ok, Handle} | Error when
+      ChannelPid :: pid(),
+      Path :: string(),
+      Mode :: [read | write | {crypto, tar_crypto_spec()} ],
+      Handle :: term(),
+      Error :: {error, reason()} .
 open_tar(Pid, File, Mode) ->
     open_tar(Pid, File, Mode, ?FILEOP_TIMEOUT).
+-spec open_tar(ChannelPid, Path, Mode, Timeout) -> {ok, Handle} | Error when
+      ChannelPid :: pid(),
+      Path :: string(),
+      Mode :: [read | write | {crypto, tar_crypto_spec()} ],
+      Timeout :: timeout(),
+      Handle :: term(),
+      Error :: {error, reason()} .
 open_tar(Pid, File, Mode, FileOpTimeout) ->
     case {lists:member(write,Mode),
 	  lists:member(read,Mode),
-	  Mode -- [read,write]} of
+	  Mode -- [write,read]} of
 	{true,false,[]} ->
 	    {ok,Handle} = open(Pid, File, [write], FileOpTimeout),
 	    erl_tar:init(Pid, write,
@@ -264,13 +327,33 @@ open_tar(Pid, File, Mode, FileOpTimeout) ->
     end.
 
 
+-spec opendir(ChannelPid, Path) -> {ok, Handle} | Error when
+      ChannelPid :: pid(),
+      Path :: string(),
+      Handle :: term(),
+      Error :: {error, reason()} .
 opendir(Pid, Path) ->
     opendir(Pid, Path, ?FILEOP_TIMEOUT).
+-spec opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | Error when
+      ChannelPid :: pid(),
+      Path :: string(),
+      Timeout :: timeout(),
+      Handle :: term(),
+      Error :: {error, reason()} .
 opendir(Pid, Path, FileOpTimeout) ->
     call(Pid, {opendir, false, Path}, FileOpTimeout).
 
+-spec close(ChannelPid, Handle) -> ok | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Error :: {error, reason()} .
 close(Pid, Handle) ->
     close(Pid, Handle, ?FILEOP_TIMEOUT).
+-spec close(ChannelPid, Handle, Timeout) -> ok | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Timeout :: timeout(),
+      Error :: {error, reason()} .
 close(Pid, Handle, FileOpTimeout) ->
     call(Pid, {close,false,Handle}, FileOpTimeout).
 
@@ -279,47 +362,149 @@ readdir(Pid,Handle) ->
 readdir(Pid,Handle, FileOpTimeout) ->
     call(Pid, {readdir,false,Handle}, FileOpTimeout).
 
+-spec pread(ChannelPid, Handle, Position, Len) -> {ok, Data} | eof | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Position :: integer(),
+      Len :: integer(),
+      Data :: string() | binary(),
+      Error :: {error, reason()}.
 pread(Pid, Handle, Offset, Len) ->
     pread(Pid, Handle, Offset, Len, ?FILEOP_TIMEOUT).
+
+-spec pread(ChannelPid, Handle, Position, Len, Timeout) -> {ok, Data} | eof | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Position :: integer(),
+      Len :: integer(),
+      Timeout :: timeout(),
+      Data :: string() | binary(),
+      Error :: {error, reason()}.
 pread(Pid, Handle, Offset, Len, FileOpTimeout) ->
     call(Pid, {pread,false,Handle, Offset, Len}, FileOpTimeout).
 
+
+-spec read(ChannelPid, Handle, Len) -> {ok, Data} | eof | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Len :: integer(),
+      Data :: string() | binary(),
+      Error :: {error, reason()}.
 read(Pid, Handle, Len) ->
     read(Pid, Handle, Len, ?FILEOP_TIMEOUT).
+
+-spec read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Len :: integer(),
+      Timeout :: timeout(),
+      Data :: string() | binary(),
+      Error :: {error, reason()}.
 read(Pid, Handle, Len, FileOpTimeout) ->
     call(Pid, {read,false,Handle, Len}, FileOpTimeout).
 
+
 %% TODO this ought to be a cast! Is so in all practical meaning
 %% even if it is obscure!
+-spec apread(ChannelPid, Handle, Position, Len) -> {async, N} | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Position :: integer(),
+      Len :: integer(),
+      Error :: {error, reason()},
+      N :: term() .
 apread(Pid, Handle, Offset, Len) ->
     call(Pid, {pread,true,Handle, Offset, Len}, infinity).
 
 %% TODO this ought to be a cast! 
+-spec aread(ChannelPid, Handle, Len) -> {async, N} | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Len :: integer(),
+      Error :: {error, reason()},
+      N :: term() .
 aread(Pid, Handle, Len) ->
     call(Pid, {read,true,Handle, Len}, infinity).
 
+
+-spec pwrite(ChannelPid, Handle, Position, Data) -> ok | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Position :: integer(),
+      Data :: iolist(),
+      Error :: {error, reason()}.
 pwrite(Pid, Handle, Offset, Data) ->
     pwrite(Pid, Handle, Offset, Data, ?FILEOP_TIMEOUT).
+
+-spec pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Position :: integer(),
+      Data :: iolist(),
+      Timeout :: timeout(),
+      Error :: {error, reason()}.
 pwrite(Pid, Handle, Offset, Data, FileOpTimeout) ->
     call(Pid, {pwrite,false,Handle,Offset,Data}, FileOpTimeout).
 
+
+-spec write(ChannelPid, Handle, Data) -> ok | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Data :: iodata(),
+      Error :: {error, reason()}.
 write(Pid, Handle, Data) ->
     write(Pid, Handle, Data, ?FILEOP_TIMEOUT).
+
+-spec write(ChannelPid, Handle, Data, Timeout) -> ok | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Data :: iodata(),
+      Timeout :: timeout(),
+      Error :: {error, reason()}.
 write(Pid, Handle, Data, FileOpTimeout) ->
     call(Pid, {write,false,Handle,Data}, FileOpTimeout).
 
 %% TODO this ought to be a cast! Is so in all practical meaning
 %% even if it is obscure!
+-spec apwrite(ChannelPid, Handle, Position, Data) -> {async, N} | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Position :: integer(),
+      Data :: binary(),
+      Error :: {error, reason()},
+      N :: term() .
 apwrite(Pid, Handle, Offset, Data) ->
     call(Pid, {pwrite,true,Handle,Offset,Data}, infinity).
 
 %% TODO this ought to be a cast!  Is so in all practical meaning
 %% even if it is obscure!
+-spec awrite(ChannelPid, Handle, Data) -> {async, N} | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Data :: binary(),
+      Error :: {error, reason()},
+      N :: term() .
 awrite(Pid, Handle, Data) ->
     call(Pid, {write,true,Handle,Data}, infinity).
 
+-spec position(ChannelPid, Handle, Location) -> {ok, NewPosition} | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Location :: Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof,
+      Offset :: integer(),
+      NewPosition :: integer(),
+      Error :: {error, reason()}.
 position(Pid, Handle, Pos) ->
     position(Pid, Handle, Pos, ?FILEOP_TIMEOUT).
+
+-spec position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition} | Error when
+      ChannelPid :: pid(),
+      Handle :: term(),
+      Location :: Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur | eof,
+      Timeout :: timeout(),
+      Offset :: integer(),
+      NewPosition :: integer(),
+      Error :: {error, reason()}.
 position(Pid, Handle, Pos, FileOpTimeout) ->
     call(Pid, {position, Handle, Pos}, FileOpTimeout).
 
@@ -328,8 +513,21 @@ real_path(Pid, Path) ->
 real_path(Pid, Path, FileOpTimeout) ->
     call(Pid, {real_path, false, Path}, FileOpTimeout).
 
+
+-spec read_file_info(ChannelPid, Name) -> {ok, FileInfo} | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      FileInfo :: file:file_info(),
+      Error :: {error, reason()}.
 read_file_info(Pid, Name) ->
     read_file_info(Pid, Name, ?FILEOP_TIMEOUT).
+
+-spec read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      Timeout :: timeout(),
+      FileInfo :: file:file_info(),
+      Error :: {error, reason()}.
 read_file_info(Pid, Name, FileOpTimeout) ->
     call(Pid, {read_file_info,false,Name}, FileOpTimeout).
 
@@ -338,18 +536,57 @@ get_file_info(Pid, Handle) ->
 get_file_info(Pid, Handle, FileOpTimeout) ->
     call(Pid, {get_file_info,false,Handle}, FileOpTimeout).
 
+
+-spec write_file_info(ChannelPid, Name, FileInfo) -> ok | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      FileInfo :: file:file_info(),
+      Error :: {error, reason()}.
 write_file_info(Pid, Name, Info) ->
     write_file_info(Pid, Name, Info, ?FILEOP_TIMEOUT).
+
+-spec write_file_info(ChannelPid, Name, FileInfo, Timeout) -> ok | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      FileInfo :: file:file_info(),
+      Timeout :: timeout(),
+      Error :: {error, reason()}.
 write_file_info(Pid, Name, Info, FileOpTimeout) ->
     call(Pid, {write_file_info,false,Name, Info}, FileOpTimeout).
 
+
+-spec read_link_info(ChannelPid, Name) -> {ok, FileInfo} | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      FileInfo :: file:file_info(),
+      Error :: {error, reason()}.
 read_link_info(Pid, Name) ->
     read_link_info(Pid, Name, ?FILEOP_TIMEOUT).
+
+-spec read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      FileInfo :: file:file_info(),
+      Timeout :: timeout(),
+      Error :: {error, reason()}.
 read_link_info(Pid, Name, FileOpTimeout) ->
     call(Pid, {read_link_info,false,Name}, FileOpTimeout).
 
+
+-spec read_link(ChannelPid, Name) -> {ok, Target} | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      Target :: string(),
+      Error :: {error, reason()}.
 read_link(Pid, LinkName) ->
     read_link(Pid, LinkName, ?FILEOP_TIMEOUT).
+
+-spec read_link(ChannelPid, Name, Timeout) -> {ok, Target} | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      Target :: string(),
+      Timeout :: timeout(),
+      Error :: {error, reason()}.
 read_link(Pid, LinkName, FileOpTimeout) ->
     case call(Pid, {read_link,false,LinkName}, FileOpTimeout) of
 	 {ok, [{Name, _Attrs}]} ->
@@ -358,28 +595,79 @@ read_link(Pid, LinkName, FileOpTimeout) ->
 	    ErrMsg
     end.
 
+-spec make_symlink(ChannelPid, Name, Target) -> ok | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      Target :: string(),
+      Error :: {error, reason()} .
 make_symlink(Pid, Name, Target) ->
     make_symlink(Pid, Name, Target, ?FILEOP_TIMEOUT).
+-spec make_symlink(ChannelPid, Name, Target, Timeout) -> ok | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      Target :: string(),
+      Timeout :: timeout(),
+      Error :: {error, reason()} .
 make_symlink(Pid, Name, Target, FileOpTimeout) ->
     call(Pid, {make_symlink,false, Name, Target}, FileOpTimeout).
 
+
+-spec rename(ChannelPid, OldName, NewName) -> ok | Error when
+      ChannelPid :: pid(),
+      OldName :: string(),
+      NewName :: string(),
+      Error :: {error, reason()}.
 rename(Pid, FromFile, ToFile) ->
     rename(Pid, FromFile, ToFile, ?FILEOP_TIMEOUT).
+
+-spec rename(ChannelPid, OldName, NewName, Timeout) -> ok | Error when
+      ChannelPid :: pid(),
+      OldName :: string(),
+      NewName :: string(),
+      Timeout :: timeout(),
+      Error :: {error, reason()}.
 rename(Pid, FromFile, ToFile, FileOpTimeout) ->
     call(Pid, {rename,false,FromFile, ToFile}, FileOpTimeout).
 
+-spec delete(ChannelPid, Name) -> ok | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      Error :: {error, reason()} .
 delete(Pid, Name) ->
     delete(Pid, Name, ?FILEOP_TIMEOUT).
+-spec delete(ChannelPid, Name, Timeout) -> ok | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      Timeout :: timeout(),
+      Error :: {error, reason()} .
 delete(Pid, Name, FileOpTimeout) ->
     call(Pid, {delete,false,Name}, FileOpTimeout).
 
+-spec make_dir(ChannelPid, Name) -> ok | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      Error :: {error, reason()} .
 make_dir(Pid, Name) ->
     make_dir(Pid, Name, ?FILEOP_TIMEOUT).
+-spec make_dir(ChannelPid, Name, Timeout) -> ok | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      Timeout :: timeout(),
+      Error :: {error, reason()} .
 make_dir(Pid, Name, FileOpTimeout) ->
     call(Pid, {make_dir,false,Name}, FileOpTimeout).
 
+-spec del_dir(ChannelPid, Name) -> ok | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      Error :: {error, reason()} .
 del_dir(Pid, Name) ->
     del_dir(Pid, Name, ?FILEOP_TIMEOUT).
+-spec del_dir(ChannelPid, Name, Timeout) -> ok | Error when
+      ChannelPid :: pid(),
+      Name :: string(),
+      Timeout :: timeout(),
+      Error :: {error, reason()} .
 del_dir(Pid, Name, FileOpTimeout) ->
     call(Pid, {del_dir,false,Name}, FileOpTimeout).
 
@@ -396,9 +684,21 @@ recv_window(Pid, FileOpTimeout) ->
     call(Pid, recv_window, FileOpTimeout).
 
 
+-spec list_dir(ChannelPid, Path) -> {ok,FileNames} | Error when
+      ChannelPid :: pid(),
+      Path :: string(),
+      FileNames :: [FileName],
+      FileName :: string(),
+      Error :: {error, reason()} .
 list_dir(Pid, Name) ->
     list_dir(Pid, Name, ?FILEOP_TIMEOUT).
-
+-spec list_dir(ChannelPid, Path, Timeout) -> {ok,FileNames} | Error when
+      ChannelPid :: pid(),
+      Path :: string(),
+      Timeout :: timeout(),
+      FileNames :: [FileName],
+      FileName :: string(),
+      Error :: {error, reason()} .
 list_dir(Pid, Name, FileOpTimeout) ->
     case opendir(Pid, Name, FileOpTimeout) of
 	{ok,Handle} ->
@@ -429,9 +729,20 @@ do_list_dir(Pid, Handle, FileOpTimeout, Acc) ->
     end.
 
 
+-spec read_file(ChannelPid, File) -> {ok, Data} | Error when
+      ChannelPid :: pid(),
+      File :: string(),
+      Data :: binary(),
+      Error :: {error, reason()}.
 read_file(Pid, Name) ->
     read_file(Pid, Name, ?FILEOP_TIMEOUT).
 
+-spec read_file(ChannelPid, File, Timeout) -> {ok, Data} | Error when
+      ChannelPid :: pid(),
+      File :: string(),
+      Data :: binary(),
+      Timeout :: timeout(),
+      Error :: {error, reason()}.
 read_file(Pid, Name, FileOpTimeout) ->
     case open(Pid, Name, [read, binary], FileOpTimeout) of
 	{ok, Handle} ->
@@ -453,9 +764,20 @@ read_file_loop(Pid, Handle, PacketSz, FileOpTimeout, Acc) ->
 	    Error
     end.
 
+-spec write_file(ChannelPid, File, Data) -> ok | Error when
+      ChannelPid :: pid(),
+      File :: string(),
+      Data :: iodata(),
+      Error :: {error, reason()}.
 write_file(Pid, Name, List) ->
     write_file(Pid, Name, List, ?FILEOP_TIMEOUT).
 
+-spec write_file(ChannelPid, File, Data, Timeout) -> ok | Error when
+      ChannelPid :: pid(),
+      File :: string(),
+      Data :: iodata(),
+      Timeout :: timeout(),
+      Error :: {error, reason()}.
 write_file(Pid, Name, List, FileOpTimeout) when is_list(List) ->
     write_file(Pid, Name, list_to_binary(List), FileOpTimeout);
 write_file(Pid, Name, Bin, FileOpTimeout) ->