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 around types #9298

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

ssh: polish docs around types #9298

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a66a465
ssh: polish docs around types
u3s Jan 13, 2025
2fcaee9
ssh: fix ssh_sftp:start_channel docs
u3s Jan 14, 2025
fe22e0b
ssh: info about receiving large exec output
u3s Jan 31, 2025
e6dec1e
ssh: type categories fixup in ssh manual
u3s Jan 31, 2025
c750b7e
ssh: move type description for conn_info_channels
u3s Jan 31, 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
26 changes: 15 additions & 11 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,8 @@ The directory could be changed with the option
[{type,<<"Client Options">>},
{type,<<"Daemon Options">>},
{type,<<"Common Options">>},
{type,<<"Other data types">>}]}).
{type,<<"Deprecated Types">>},
{type,<<"Other Data Types">>}]}).

-include("ssh.hrl").
-include("ssh_connect.hrl").
Expand Down Expand Up @@ -174,8 +175,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 Types">>}).
-opaque ssh_daemon_ref() :: daemon_ref().
-doc(#{title => <<"Deprecated Types">>}).
-opaque ssh_connection_ref() :: connection_ref().
-doc(#{title => <<"Deprecated Types">>}).
-opaque ssh_channel_id() :: channel_id().


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

Returned by the functions [`daemon/1,2,3`](`daemon/1`).
""".
-doc(#{title => <<"Other data types">>}).
-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">>}).
-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 +229,7 @@ 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">>}).
-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.

Could we perhaps find better categories than "Other" ?
Maybe not all now other belong in the same category!?

Copy link
Contributor Author

@u3s u3s Jan 31, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I don't have an idea now. But I removed the title so we just have a generic Types category with them ... maybe it is good enough as they are sort of general types.

-type connection_ref() :: pid(). % should be -opaque, but that gives problems

%%--------------------------------------------------------------------
Expand Down Expand Up @@ -427,13 +431,13 @@ close(ConnectionRef) ->
%%--------------------------------------------------------------------
%% Description: Retrieves information about a connection.
%%---------------------------------------------------------------------
-doc(#{title => <<"Other data types">>}).
-doc(#{title => <<"Other Data Types">>}).
-type version() :: {protocol_version(), software_version()}.
-doc(#{title => <<"Other data types">>}).
-doc(#{title => <<"Other Data Types">>}).
-type protocol_version() :: {Major::pos_integer(), Minor::non_neg_integer()}.
-doc(#{title => <<"Other data types">>}).
-doc(#{title => <<"Other Data Types">>}).
-type software_version() :: string().
-doc(#{title => <<"Other data types">>}).
-doc(#{title => <<"Other Data Types">>}).
-type conn_info_algs() :: [{kex, kex_alg()}
| {hkey, pubkey_alg()}
| {encrypt, cipher_alg()}
Expand All @@ -451,10 +455,10 @@ 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.
""".
-doc(#{title => <<"Other data types">>}).
-doc(#{title => <<"Other Data Types">>}).
-type conn_info_channels() :: [proplists:proplist()].

-doc(#{title => <<"Other data types">>}).
-doc(#{title => <<"Other Data Types">>}).
-type connection_info_tuple() ::
{client_version, version()}
| {server_version, version()}
Expand Down Expand Up @@ -691,7 +695,7 @@ 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.
""".
-doc(#{title => <<"Other data types">>}).
-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?

-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(), PeerAddress::inet:ip_address(), Reason::term()) -> _)}
| {connectfun, fun((User::string(), PeerAddress::inet:ip_address(), 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
56 changes: 26 additions & 30 deletions lib/ssh/src/ssh_sftp.erl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -130,38 +130,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}).
-spec start_channel(ssh:open_socket(),
[ssh:client_option() | sftp_option()]
)
-> {ok,pid(),ssh:connection_ref()} | {error,reason()};
-doc """
Starts new ssh channel for communicating with the SFTP server.

(ssh:connection_ref(),
[sftp_option()]
)
-> {ok,pid()} | {ok,pid(),ssh:connection_ref()} | {error,reason()};
Starts an ssh channel when first argument is a connection reference.

(ssh:host(),
[ssh:client_option() | sftp_option()]
)
-> {ok,pid(),ssh:connection_ref()} | {error,reason()} .
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(), [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()}.
start_channel(Cm, UserOptions0) when is_pid(Cm) ->
UserOptions = legacy_timeout(UserOptions0),
Timeout = proplists:get_value(timeout, UserOptions, infinity),
Expand Down Expand Up @@ -209,14 +209,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