From 06a782d7b5868237fa260b293f50646f9883cf33 Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Wed, 18 Apr 2018 20:17:49 +0200 Subject: ssh: Use -spec and -type for documentation generation --- lib/ssh/doc/src/ssh_channel.xml | 95 +++++++++++++++++------------------------ 1 file changed, 38 insertions(+), 57 deletions(-) (limited to 'lib/ssh/doc/src/ssh_channel.xml') diff --git a/lib/ssh/doc/src/ssh_channel.xml b/lib/ssh/doc/src/ssh_channel.xml index 7b598494f7..0355f7bf52 100644 --- a/lib/ssh/doc/src/ssh_channel.xml +++ b/lib/ssh/doc/src/ssh_channel.xml @@ -46,6 +46,7 @@ the ssh applications supervisor tree.

+

When implementing an ssh subsystem, use -behaviour(ssh_daemon_channel) instead of -behaviour(ssh_channel). The reason is that the only relevant callback functions for subsystems are @@ -55,33 +56,6 @@

-
- DATA TYPES - -

Type definitions that are used more than once in this module, - or abstractions to indicate the intended use of the data - type, or both:

- - - boolean() = -

true | false

 - string() = -

list of ASCII characters

 - timeout() = -

infinity | integer() in milliseconds

 - ssh_connection_ref() = -

opaque() -as returned by - ssh:connect/3 or sent to an SSH channel process

 - ssh_channel_id() = -

integer()

 - ssh_data_type_code() = -

1 ("stderr") | 0 ("normal") are - the valid values, - see RFC 4254 - Section 5.2

 - -
- call(ChannelRef, Msg) -> @@ -89,7 +63,7 @@ Makes a synchronous call to a channel. ChannelRef = pid() - As returned by ssh_channel:start_link/4 + As returned by start_link/4 Msg = term() Timeout = timeout() Reply = term() @@ -113,7 +87,7 @@ ChannelRef and returns ok. ChannelRef = pid() - As returned by ssh_channel:start_link/4 + As returned by start_link/4 Msg = term() @@ -131,7 +105,7 @@ Makes an existing process an ssh_channel process. State = term() - as returned by ssh_channel:init/1 + as returned by init/1

Makes an existing process an ssh_channel @@ -141,7 +115,7 @@ one of the start functions in proc_lib, see the proc_lib(3) manual page in STDLIB. The user is responsible for any initialization of the process - and must call ssh_channel:init/1. + and must call init/1.

@@ -160,18 +134,21 @@ The following options must be present:

- + {channel_cb, atom()}

The module that implements the channel behaviour.

 - + {init_args(), list()}

The list of arguments to the init function of the callback module.

 - -

Reference to the ssh connection as returned by ssh:connect/3

 + {cm, ssh:connection_ref()} +

Reference to the ssh connection as returned by + ssh:connect/3. +

- -

Id of the ssh channel.

 + {channel_id, ssh:channel_id()} +

Id of the ssh channel as returned by + ssh_connection:session_channel/2,4. +

@@ -179,8 +156,8 @@ user. The user only needs to call if the channel process needs to be started with help of proc_lib instead of calling - ssh_channel:start/4 or - ssh_channel:start_link/4.

+ start/4 or + start_link/4.

@@ -201,26 +178,31 @@ the callback function handle_call/3. Reply is an arbitrary term, which is given back to the client as the return value of - ssh_channel:call/[2,3].

+ call/[2,3].

- + start(SshConnection, ChannelId, ChannelCb, CbInitArgs) -> start_link(SshConnection, ChannelId, ChannelCb, CbInitArgs) -> {ok, ChannelRef} | {error, Reason} Starts a process that handles an SSH channel. - SshConnection = ssh_connection_ref() - ChannelId = ssh_channel_id() + SshConnection = ssh:connection_ref() + As returned by ssh:connect/3 + + ChannelId = ssh:channel_id() As returned by ssh_connection:session_channel/[2,4]. + ChannelCb = atom() Name of the module implementing the service-specific parts of the channel. + CbInitArgs = [term()] Argument list for the init function in the callback module. + ChannelRef = pid() @@ -295,7 +277,7 @@ initial channel state if the initializations succeed. Args = term() - Last argument to ssh_channel:start_link/4. + Last argument to start_link/4. State = term() Reason = term() @@ -311,24 +293,24 @@ Module:handle_call(Msg, From, State) -> Result Handles messages sent by calling - ssh_channel:call/[2,3]. + call/[2,3]. Msg = term() From = opaque() Is to be used as argument to - ssh_channel:reply/2 + reply/2 State = term() Result = {reply, Reply, NewState} | {reply, Reply, NewState, timeout()} | {noreply, NewState} | {noreply , NewState, timeout()} | {stop, Reason, Reply, NewState} | {stop, Reason, NewState} Reply = term() - Will be the return value of ssh_channel:call/[2,3] + Will be the return value of call/[2,3] NewState = term() Reason = term()

Handles messages sent by calling - ssh_channel:call/[2,3] + call/[2,3]

For more detailed information on time-outs,, see Section CALLBACK TIME-OUTS.

@@ -338,7 +320,7 @@ Module:handle_cast(Msg, State) -> Result Handles messages sent by calling - ssh_channel:cact/2. + cast/2. Msg = term() State = term() @@ -349,7 +331,7 @@

Handles messages sent by calling - ssh_channel:cast/2. + cast/2.

For more detailed information on time-outs, see Section CALLBACK TIME-OUTS.

@@ -364,7 +346,7 @@ call, or cast messages sent to the channel. Msg = timeout | term() - ChannelId = ssh_channel_id() + ChannelId = ssh:channel_id() State = term() @@ -376,11 +358,10 @@ function and all channels are to handle the following message.

- + {ssh_channel_up, ssh:channel_id(), ssh:connection_ref()}

This is the first message that the channel receives. It is sent just before the ssh_channel:init/1 function + marker="#init-1">init/1 function returns successfully. This is especially useful if the server wants to send a message to the client without first receiving a message from it. If the message is not @@ -397,7 +378,7 @@ Handles ssh connection protocol messages. Msg = ssh_connection:event() - ChannelId = ssh_channel_id() + ChannelId = ssh:channel_id() State = term() @@ -410,7 +391,7 @@ ssh_channel behavior.

- + {closed, ssh:channel_id()}

The channel behavior sends a close message to the other side, if such a message has not already been sent. Then it terminates the channel with reason normal.

 -- cgit v1.2.3