ssh: Update ssh_sftp:start_channel documentation and code

The Typing in the old documentation was not up-to-date.  The option
handling and definition is slightly re-worked in the code also.

Some comments added and a function moved inside the module.

3 files changed, 72 insertions, 24 deletions

diff --git a/lib/ssh/doc/src/ssh_sftp.xml b/lib/ssh/doc/src/ssh_sftp.xml
index 76d2b21946..f9f1e0953b 100644
--- a/lib/ssh/doc/src/ssh_sftp.xml
+++ b/lib/ssh/doc/src/ssh_sftp.xml
@@ -38,6 +38,12 @@
   </description>
   
   <datatypes>
+    <datatype>
+      <name name="sftp_option"/>
+      <desc>
+      </desc>
+    </datatype>
+
     <datatype_title>Error cause</datatype_title>
     <datatype>
       <name name="reason"/>
@@ -423,25 +429,27 @@
 
     <func>
       <name since="">start_channel(ConnectionRef) -></name>
-      <name since="">start_channel(ConnectionRef, Options) ->
-      {ok, Pid} | {error, reason()|term()}</name>
+      <name since="">start_channel(ConnectionRef, SftpOptions) ->
+      {ok, ChannelPid} | Error</name>
 
+      <name since="">start_channel(Host) -></name>
       <name since="">start_channel(Host, Options) -></name>
-      <name since="">start_channel(Host, Port, Options) -> 
-      {ok, Pid, ConnectionRef} | {error, reason()|term()}</name>
-
+      <name since="">start_channel(Host, Port, Options) -></name>
       <name since="">start_channel(TcpSocket) -></name>
       <name since="">start_channel(TcpSocket, Options) ->
-      {ok, Pid, ConnectionRef} | {error, reason()|term()}</name>
+      {ok, ChannelPid, ConnectionRef} | Error</name>
 
       <fsummary>Starts an SFTP client.</fsummary>
       <type>
-        <v>Host = string()</v>
-        <v>ConnectionRef = connection_ref()</v>
-        <v>Port = integer()</v>
-	<v>TcpSocket = port()</v>
-	<d>The socket is supposed to be from <seealso marker="kernel:gen_tcp#connect-3">gen_tcp:connect</seealso> or <seealso marker="kernel:gen_tcp#accept-1">gen_tcp:accept</seealso> with option <c>{active,false}</c></d>
-        <v>Options = [{Option, Value}]</v>
+        <v>Host = <seealso marker="ssh:ssh#type-host">ssh:host()</seealso></v>
+        <v>Port = <seealso marker="kernel:inet#type-port_number">inet:port_number()</seealso></v>
+	<v>TcpSocket = <seealso marker="ssh:ssh#type-open_socket">ssh:open_socket()</seealso></v>
+	<v>Options = [  <seealso marker="#type-sftp_option">sftp_option()</seealso>
+		      | <seealso marker="ssh:ssh#type-client_option">ssh:client_option()</seealso> ]</v>
+	<v>SftpOptions = [  <seealso marker="#type-sftp_option">sftp_option()</seealso> ]</v>
+	<v>ChannelPid = pid()</v>
+        <v>ConnectionRef = <seealso marker="ssh:ssh#type-connection_ref">ssh:connection_ref()</seealso></v>
+	<v>Error = {error, <seealso marker="#type-reason">reason()</seealso>}</v>
       </type>
       <desc>
 	<p>If no connection reference is provided, a connection is set
diff --git a/lib/ssh/src/ssh.erl b/lib/ssh/src/ssh.erl
index ff5aee14d7..32f10c797d 100644
--- a/lib/ssh/src/ssh.erl
+++ b/lib/ssh/src/ssh.erl
@@ -66,6 +66,8 @@
               cipher_alg/0,
               mac_alg/0,
               compression_alg/0,
+              host/0,
+              open_socket/0,
               ip_port/0
 	     ]).
 
diff --git a/lib/ssh/src/ssh_sftp.erl b/lib/ssh/src/ssh_sftp.erl
index 9162de3487..4b6e187c3a 100644
--- a/lib/ssh/src/ssh_sftp.erl
+++ b/lib/ssh/src/ssh_sftp.erl
@@ -92,34 +92,63 @@
 -define(XF(S), S#state.xf).
 -define(REQID(S), S#state.req_id).
 
+-type sftp_option() :: {timeout, timeout()}
+                     | {sftp_vsn, pos_integer()}
+                     | {window_size, pos_integer()}
+                     | {packet_size, pos_integer()} .
 
 -type reason() :: atom() | string() | tuple() .
 
 %%====================================================================
 %% API
 %%====================================================================
+
+
+%%%================================================================
+%%%
+
+%%%----------------------------------------------------------------
+%%% start_channel/1
+
 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) ->
     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/2
+
+%%% -spec:s are as if Dialyzer handled signatures for separate
+%%% function clauses.
+
+-spec start_channel(ssh:open_socket(),
+                    [ssh:client_options() | sftp_option()]
+                   )
+                   -> {ok,pid(),ssh:connection_ref()} | {error,reason()};
+
+                   (ssh:connection_ref(),
+                    [sftp_option()]
+                   )
+                   -> {ok,pid()}  | {ok,pid(),ssh:connection_ref()} | {error,reason()};
+
+                   (ssh:host(),
+                    [ssh:client_options() | sftp_option()]
+                   )
+                   -> {ok,pid(),ssh:connection_ref()} | {error,reason()} .
 
 start_channel(Socket, UserOptions) when is_port(Socket) ->
-    {SshOpts, _ChanOpts, SftpOpts} = handle_options(UserOptions),
+    {SshOpts, ChanOpts, SftpOpts} = handle_options(UserOptions),
     Timeout =   % A mixture of ssh:connect and ssh_sftp:start_channel:
         proplists:get_value(connect_timeout, SshOpts,
                             proplists:get_value(timeout, SftpOpts, infinity)),
     case ssh:connect(Socket, SshOpts, Timeout) of
 	{ok,Cm} ->
-	    case start_channel(Cm, UserOptions) of
+	    case start_channel(Cm, ChanOpts ++ SftpOpts) of
 		{ok, Pid} ->
 		    {ok, Pid, Cm};
 		Error ->
@@ -155,8 +184,14 @@ 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/3
+
+-spec start_channel(ssh:host(),
+                    inet:port_number(),
+                    [ssh:client_option() | sftp_option()]
+                   )
+                   -> {ok,pid(),ssh:connection_ref()} | {error,reason()}.
 
 start_channel(Host, Port, UserOptions) ->
     {SshOpts, ChanOpts, SftpOpts} = handle_options(UserOptions),
@@ -182,7 +217,12 @@ start_channel(Host, Port, UserOptions) ->
 	    Error
     end.
 
+%%% Helper for start_channel
 
+wait_for_version_negotiation(Pid, Timeout) ->
+    call(Pid, wait_for_version_negotiation, Timeout).
+
+%%%----------------------------------------------------------------
 -spec stop_channel(ChannelPid) -> ok when
       ChannelPid :: pid().
 
@@ -203,9 +243,7 @@ stop_channel(Pid) ->
 	    ok
     end.
 
-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(),