Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ssh: polish docs #9298

Open
wants to merge 8 commits into
base: maint
Choose a base branch
from
Open

ssh: polish docs #9298

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
f08c0bd
ssh: polish docs around types
u3s Jan 13, 2025
0f05242
ssh: fix ssh_sftp:start_channel docs
u3s Jan 14, 2025
d39a2aa
ssh: info about receiving large exec output
u3s Jan 31, 2025
7cf85d3
ssh: type categories fixup in ssh manual
u3s Jan 31, 2025
1684061
ssh: move type description for conn_info_channels
u3s Jan 31, 2025
320737a
ssh: typo fix in using_ssh.md
u3s Feb 3, 2025
5471ae5
ssh: fix docs for `options` note
u3s Feb 3, 2025
e25585a
ssh: ssh_sftp manual fix
u3s Feb 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion lib/ssh/doc/guides/using_ssh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -535,7 +535,7 @@ DecryptFun =
end,

Cr = {InitFun,DecryptFun},
{ok,HandleRead} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [read,{crypto,Cw}]),
{ok,HandleRead} = ssh_sftp:open_tar(ChannelPid, ?tar_file_name, [read,{crypto,Cr}]),
{ok,NameValueList} = erl_tar:extract(HandleRead,[memory]),
ok = erl_tar:close(HandleRead),
```
Expand Down
29 changes: 12 additions & 17 deletions lib/ssh/src/ssh.erl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ The directory could be changed with the option
[{type,<<"Client Options">>},
{type,<<"Daemon Options">>},
{type,<<"Common Options">>},
{type,<<"Other data types">>}]}).
{type,<<"Deprecated">>}]}).

-include("ssh.hrl").
-include("ssh_connect.hrl").
Expand Down Expand Up @@ -174,8 +174,11 @@ The directory could be changed with the option

%%% "Deprecated" types export:
-export_type([ssh_daemon_ref/0, ssh_connection_ref/0, ssh_channel_id/0]).
-doc(#{title => <<"Deprecated">>}).
-opaque ssh_daemon_ref() :: daemon_ref().
-doc(#{title => <<"Deprecated">>}).
-opaque ssh_connection_ref() :: connection_ref().
-doc(#{title => <<"Deprecated">>}).
-opaque ssh_channel_id() :: channel_id().


Expand Down Expand Up @@ -208,15 +211,13 @@ Opaque data type representing a daemon.

Returned by the functions [`daemon/1,2,3`](`daemon/1`).
""".
-doc(#{title => <<"Other data types">>}).
-opaque daemon_ref() :: pid() .
-doc """
Opaque data type representing a channel inside a connection.

Returned by the functions
[ssh_connection:session_channel/2,4](`ssh_connection:session_channel/2`).
""".
-doc(#{title => <<"Other data types">>}).
-opaque channel_id() :: non_neg_integer().
-doc """
Opaque data type representing a connection between a client and a server
Expand All @@ -225,7 +226,6 @@ Opaque data type representing a connection between a client and a server
Returned by the functions [`connect/2,3,4`](`connect/3`) and
[`ssh_sftp:start_channel/2,3`](`ssh_sftp:start_channel/2`).
""".
-doc(#{title => <<"Other data types">>}).
-type connection_ref() :: pid(). % should be -opaque, but that gives problems

%%--------------------------------------------------------------------
Expand Down Expand Up @@ -427,13 +427,9 @@ close(ConnectionRef) ->
%%--------------------------------------------------------------------
%% Description: Retrieves information about a connection.
%%---------------------------------------------------------------------
-doc(#{title => <<"Other data types">>}).
-type version() :: {protocol_version(), software_version()}.
-doc(#{title => <<"Other data types">>}).
-type protocol_version() :: {Major::pos_integer(), Minor::non_neg_integer()}.
-doc(#{title => <<"Other data types">>}).
-type software_version() :: string().
-doc(#{title => <<"Other data types">>}).
-type conn_info_algs() :: [{kex, kex_alg()}
| {hkey, pubkey_alg()}
| {encrypt, cipher_alg()}
Expand All @@ -445,16 +441,15 @@ close(ConnectionRef) ->
| {send_ext_info, boolean()}
| {recv_ext_info, boolean()}
].
-type conn_info_channels() :: [proplists:proplist()].

-doc """
Return values from the `connection_info/1` and `connection_info/2` functions.

In the `option` info tuple are only the options included that differs from the
default values.
> #### Note {: .info }
>
> Note that `options` info tuple contains only items with nondefault values.
""".
-doc(#{title => <<"Other data types">>}).
-type conn_info_channels() :: [proplists:proplist()].

-doc(#{title => <<"Other data types">>}).
-type connection_info_tuple() ::
{client_version, version()}
| {server_version, version()}
Expand Down Expand Up @@ -690,10 +685,10 @@ daemon_replace_options(DaemonRef, NewUserOptions) ->
-doc """
Return values from the `daemon_info/1` and `daemon_info/2` functions.

In the `option` info tuple are only the options included that differs from the
default values.
> #### Note {: .info }
>
> Note that `options` info tuple contains only items with nondefault values.
""".
-doc(#{title => <<"Other data types">>}).
-type daemon_info_tuple() ::
{port, inet:port_number()}
| {ip, inet:ip_address()}
Expand Down
17 changes: 9 additions & 8 deletions lib/ssh/src/ssh.hrl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,16 +122,17 @@


%% Types
-doc(#{title => <<"Other Data Types">>}).
-type role() :: client | server .

-doc(#{title => <<"Other data types">>}).
-doc(#{title => <<"Other Data Types">>}).
-type host() :: string() | inet:ip_address() | loopback .
-doc """
The socket is supposed to be result of a [gen_tcp:connect](`gen_tcp:connect/3`)
or a [gen_tcp:accept](`gen_tcp:accept/1`). The socket must be in passive mode
(that is, opened with the option `{active,false})`.
""".
-doc(#{title => <<"Other data types">>}).
-doc(#{title => <<"Other Data Types">>}).
-type open_socket() :: gen_tcp:socket().

-doc """
Expand Down Expand Up @@ -514,7 +515,7 @@ protocol).
Opaque types that define experimental options that are not to be used in
products.
""".
-doc(#{title => <<"Other data types">>}).
-doc(#{title => <<"Other Data Types">>}).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is meant with opaque option? This does not make sense to me!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you mean opaque_ part in type names below?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes! I do not think options can be opaque. You need to know what it is you are setting to be able to set it. Opaque I think is used to say that the user should not care how something "looks" (is represented) it is only an abstract handle that can be used as input to the API functions of the module. A truly opaque value can only be inspected by the module implementing it. And that is why we have some values that are only documented opaque as we want users to be able to match them for equality although we do think it is an API violation to pick them apart and do things with an individual part.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And that is why we have some values that are only documented opaque as we want users to be able to match them for equality although we do think it is an API violation to pick them apart and do things with an individual part.

Testing (in-)equality of opaques with the same name is okay in master, as it does not leak any information about the contents. You can start looking into making these types actually opaque now :-)

-type opaque_common_options() ::
{transport, {atom(),atom(),atom()} }
| {vsn, {non_neg_integer(),non_neg_integer()} }
Expand Down Expand Up @@ -547,7 +548,7 @@ risk.
| gen_tcp:connect_option()
| ?COMMON_OPTION .

-doc(#{title => <<"Other data types">>}).
-doc(#{title => <<"Other Data Types">>}).
-type opaque_client_options() ::
{keyboard_interact_fun, fun((Name::iodata(),
Instruction::iodata(),
Expand Down Expand Up @@ -1149,17 +1150,17 @@ in the User's Guide chapter.
{failfun, fun((User::string(), Peer::{inet:ip_address(), inet:port_number()}, Reason::term()) -> _)}
| {connectfun, fun((User::string(), Peer::{inet:ip_address(), inet:port_number()}, Method::string()) ->_)} .

-doc(#{title => <<"Other data types">>}).
-doc(#{title => <<"Other Data Types">>}).
-type opaque_daemon_options() ::
{infofun, fun()}
| opaque_common_options().

-doc(#{title => <<"Other data types">>}).
-doc(#{title => <<"Other Data Types">>}).
-type ip_port() :: {inet:ip_address(), inet:port_number()} .

-doc(#{title => <<"Other data types">>}).
-doc(#{title => <<"Other Data Types">>}).
-type mod_args() :: {Module::atom(), Args::list()} .
-doc(#{title => <<"Other data types">>}).
-doc(#{title => <<"Other Data Types">>}).
-type mod_fun_args() :: {Module::atom(), Function::atom(), Args::list()} .


Expand Down
6 changes: 6 additions & 0 deletions lib/ssh/src/ssh_connection.erl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -417,6 +417,12 @@ request is a one-time execution that closes the channel when it is done.

See the User's Guide section on
[One-Time Execution](using_ssh.md#one-time-execution) for examples.

> #### Note {: .info }
>
> In case when command generates large amount of output data, manual
> window adjustment might be necessary in order to receive it.
> see [`ssh_connectino:adjust_window/3`](`adjust_window/3`)
""".
-spec exec(ConnectionRef, ChannelId, Command, Timeout) -> result() when
ConnectionRef :: ssh:connection_ref(),
Expand Down
45 changes: 26 additions & 19 deletions lib/ssh/src/ssh_sftp.erl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,9 @@ file transfer service available for SSH.
-define(XF(S), S#state.xf).
-define(REQID(S), S#state.req_id).

-doc """
Specifies available SFTP options.
""".
-type sftp_option() :: {timeout, timeout()}
| {sftp_vsn, pos_integer()}
| {window_size, pos_integer()}
Expand Down Expand Up @@ -130,30 +133,38 @@ The `t:tuple/0` reason are other errors like for example `{exit_status,1}`.
%%====================================================================
%% API
%%====================================================================


%%%================================================================
%%%

%%%----------------------------------------------------------------
%%% start_channel/1
-doc(#{equiv => start_channel/3}).
-doc(#{equiv => start_channel/2}).
-spec start_channel(ssh:open_socket() | ssh:connection_ref() | ssh:host()) ->
{ok, pid()} | {ok, pid(), ssh:connection_ref()} | {error, reason()}.
start_channel(Dest) ->
start_channel(Dest, []).

%%%----------------------------------------------------------------
%%% start_channel/2

%%% -spec:s are as if Dialyzer handled signatures for separate
%%% function clauses.
-doc(#{equiv => start_channel/3}).
-doc """
Starts new ssh channel for communicating with the SFTP server.

Starts an ssh channel when first argument is a connection reference.

Equivalent to [start_channel(Host, 22, UserOptions)](`start_channel/3`) when
first argument is recognized as network host.

Otherwise, first argument is treated as a network socket which will be used for
establishing new SSH connection. New connection reference will be used for
starting an SSH channel.

The returned `pid` for this process is to be used as input to all other API
functions in this module.

See also (`start_channel/3`).

""".
-spec start_channel(ssh:open_socket(), [ssh:client_option() | sftp_option()]) ->
{ok, pid(), ssh:connection_ref()} | {error,reason()};
(ssh:connection_ref(), [ssh:client_option() | sftp_option()]) ->
{ok, pid()} | {ok, pid(), ssh:connection_ref()} | {error, reason()};
(ssh:host(), [ssh:client_option() | sftp_option()]) ->
{ok, pid(), ssh:connection_ref()} | {error, reason()} .
{ok, pid(), ssh:connection_ref()} | {error, reason()}.
start_channel(Cm, UserOptions0) when is_pid(Cm) ->
UserOptions = legacy_timeout(UserOptions0),
Timeout = proplists:get_value(timeout, UserOptions, infinity),
Expand Down Expand Up @@ -201,14 +212,10 @@ start_channel(Dest, UserOptions0) ->
end
end.

%%%----------------------------------------------------------------
%%% start_channel/3
-doc """
start_channel(Host, Port, Options) ->
Starts new ssh connection and channel for communicating with the SFTP server.

If no connection reference is provided, a connection is set up, and the new
connection is returned. An SSH channel process is started to handle the
communication with the SFTP server. The returned `pid` for this process is to be
The returned `pid` for this process is to be
used as input to all other API functions in this module.

Options:
Expand Down
Loading