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 2 commits into
base: maint
Choose a base branch
from
Open

ssh: polish docs around types #9298

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 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
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!?

-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!

-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
Loading