diff --git a/HOWTO/DOCUMENTATION.md b/HOWTO/DOCUMENTATION.md index eb787f758f44..d73f7ab5cbeb 100644 --- a/HOWTO/DOCUMENTATION.md +++ b/HOWTO/DOCUMENTATION.md @@ -85,28 +85,23 @@ However, [ex_doc] is still used to generate HTML docs for the `edoc` application #### Grouping It is possible to create groups of types and/or functions within a module using -documentation metadata. To do that you need to do two things: - -1. Add the key `titles` to the `moduledoc` metadata with a list containing which - groups you want. -2. Add the key `title` to each type and/or function you want to be listed within - that group. +documentation metadata. To do that you need to add the key `group` to each type +and/or function you want to be listed within that group. Example: ```erlang -module(test). -moduledoc "A test module". --moduledoc(#{ titles => [{function, <<"Obsolete API">>}, {type, <<"Obsolete API">>}] }). -export([old_function/0]). -doc "An old type". --doc(#{ title => <<"Obsolete API">> }). +-doc(#{group => <<"Obsolete API">> }). -type old_type() :: term(). -doc "An old function". --doc(#{ title => <<"Obsolete API">> }). +-doc(#{group => <<"Obsolete API">> }). old_function() -> very_old. ``` diff --git a/erts/preloaded/src/erl_tracer.erl b/erts/preloaded/src/erl_tracer.erl index 1cfdee4fe784..3490afa316d3 100644 --- a/erts/preloaded/src/erl_tracer.erl +++ b/erts/preloaded/src/erl_tracer.erl @@ -183,8 +183,7 @@ static ERL_NIF_TERM trace(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]) } ``` """. --moduledoc(#{since => "OTP 19.0", - titles => [{callback,<<"Callback Functions">>}]}). +-moduledoc(#{since => "OTP 19.0"}). -export([enabled/3, trace/5, on_load/0]). @@ -266,7 +265,7 @@ tracee. This function can be called multiple times per tracepoint, so it is important that it is both fast and without side effects. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback enabled(TraceTag, TracerState, Tracee) -> Result when TraceTag :: trace_tag() | trace_status, TracerState :: term(), @@ -279,7 +278,7 @@ This callback is called whenever a tracepoint with trace flag If [`enabled_call/3`](`c:enabled_call/3`) is undefined, [`Module:enabled/3`](`c:enabled/3`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback enabled_call(TraceTag, TracerState, Tracee) -> Result when TraceTag :: trace_tag_call(), TracerState :: term(), @@ -292,7 +291,7 @@ This callback is called whenever a tracepoint with trace flag If [`enabled_garbage_collection/3`](`c:enabled_garbage_collection/3`) is undefined, [`Module:enabled/3`](`c:enabled/3`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback enabled_garbage_collection(TraceTag, TracerState, Tracee) -> Result when TraceTag :: trace_tag_gc(), TracerState :: term(), @@ -305,7 +304,7 @@ This callback is called whenever a tracepoint with trace flag If [`enabled_ports/3`](`c:enabled_ports/3`) is undefined, [`Module:enabled/3`](`c:enabled/3`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback enabled_ports(TraceTag, TracerState, Tracee) -> Result when TraceTag :: trace_tag_ports(), TracerState :: term(), @@ -318,7 +317,7 @@ This callback is called whenever a tracepoint with trace flag If [`enabled_procs/3`](`c:enabled_procs/3`) is undefined, [`Module:enabled/3`](`c:enabled/3`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback enabled_procs(TraceTag, TracerState, Tracee) -> Result when TraceTag :: trace_tag_procs(), TracerState :: term(), @@ -331,7 +330,7 @@ This callback is called whenever a tracepoint with trace flag If [`enabled_receive/3`](`c:enabled_receive/3`) is undefined, [`Module:enabled/3`](`c:enabled/3`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback enabled_receive(TraceTag, TracerState, Tracee) -> Result when TraceTag :: trace_tag_receive(), TracerState :: term(), @@ -344,7 +343,7 @@ This callback is called whenever a tracepoint with trace flag If [`enabled_running_ports/3`](`c:enabled_running_ports/3`) is undefined, [`Module:enabled/3`](`c:enabled/3`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback enabled_running_ports(TraceTag, TracerState, Tracee) -> Result when TraceTag :: trace_tag_running_ports(), TracerState :: term(), @@ -357,7 +356,7 @@ This callback is called whenever a tracepoint with trace flag If [`enabled_running_procs/3`](`c:enabled_running_procs/3`) is undefined, [`Module:enabled/3`](`c:enabled/3`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback enabled_running_procs(TraceTag, TracerState, Tracee) -> Result when TraceTag :: trace_tag_running_procs(), TracerState :: term(), @@ -370,7 +369,7 @@ This callback is called whenever a tracepoint with trace flag If [`enabled_send/3`](`c:enabled_send/3`) is undefined, [`Module:enabled/3`](`c:enabled/3`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback enabled_send(TraceTag, TracerState, Tracee) -> Result when TraceTag :: trace_tag_send(), TracerState :: term(), @@ -396,7 +395,7 @@ specified. For more information on what `Label` and `SeqTraceInfo` can be, see `m:seq_trace`. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback trace(seq_trace, TracerState, Label, SeqTraceInfo, Opts) -> Result when TracerState :: term(), Label :: term(), @@ -417,7 +416,7 @@ This callback is called when a tracepoint is triggered and the If [`trace_call/5`](`c:trace_call/5`) is undefined, [`Module:trace/5`](`c:trace/5`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback trace_call(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result when TraceTag :: trace_tag_call(), TracerState :: term(), @@ -433,7 +432,7 @@ callback returned `trace`. If [`trace_garbage_collection/5`](`c:trace_garbage_collection/5`) is undefined, [`Module:trace/5`](`c:trace/5`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback trace_garbage_collection(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result when TraceTag :: trace_tag_gc(), TracerState :: term(), @@ -448,7 +447,7 @@ This callback is called when a tracepoint is triggered and the If [`trace_ports/5`](`c:trace_ports/5`) is undefined, [`Module:trace/5`](`c:trace/5`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback trace_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result when TraceTag :: trace_tag(), TracerState :: term(), @@ -463,7 +462,7 @@ This callback is called when a tracepoint is triggered and the If [`trace_procs/5`](`c:trace_procs/5`) is undefined, [`Module:trace/5`](`c:trace/5`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback trace_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result when TraceTag :: trace_tag(), TracerState :: term(), @@ -478,7 +477,7 @@ This callback is called when a tracepoint is triggered and the If [`trace_receive/5`](`c:trace_receive/5`) is undefined, [`Module:trace/5`](`c:trace/5`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback trace_receive(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result when TraceTag :: trace_tag_receive(), TracerState :: term(), @@ -494,7 +493,7 @@ returned `trace`. If [`trace_running_ports/5`](`c:trace_running_ports/5`) is undefined, [`Module:trace/5`](`c:trace/5`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback trace_running_ports(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result when TraceTag :: trace_tag_running_ports(), TracerState :: term(), @@ -510,7 +509,7 @@ returned `trace`. If [`trace_running_procs/5`](`c:trace_running_procs/5`) is undefined, [`Module:trace/5`](`c:trace/5`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback trace_running_procs(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result when TraceTag :: trace_tag_running_procs(), TracerState :: term(), @@ -525,7 +524,7 @@ This callback is called when a tracepoint is triggered and the If [`trace_send/5`](`c:trace_send/5`) is undefined, [`Module:trace/5`](`c:trace/5`) is called instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.0">>}). +-doc(#{since => <<"OTP 19.0">>}). -callback trace_send(TraceTag, TracerState, Tracee, TraceTerm, Opts) -> Result when TraceTag :: trace_tag_send(), TracerState :: term(), diff --git a/lib/common_test/src/ct_hooks.erl b/lib/common_test/src/ct_hooks.erl index 638f6d818bbd..131895306f4e 100644 --- a/lib/common_test/src/ct_hooks.erl +++ b/lib/common_test/src/ct_hooks.erl @@ -45,8 +45,7 @@ For information about how to add a CTH to your suite, see section > For a minimal example of a CTH, see section > [Example CTH](ct_hooks_chapter.md#example) in the User's Guide. """. --moduledoc(#{since => "OTP R14B02", - titles => [{callback,<<"Callback Functions">>}]}). +-moduledoc(#{since => "OTP R14B02"}). %% API Exports -export([init/1]). @@ -86,7 +85,7 @@ times by `Common Test`. If not implemented, the CTH acts as if this function returned a call to `make_ref/0`. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP R14B02">>}). +-doc(#{since => <<"OTP R14B02">>}). -callback id(Opts) -> Id when Opts :: term(), Id :: term(). -doc """ @@ -107,7 +106,7 @@ Guide. For details about when `init` is called, see section [CTH Scope](ct_hooks_chapter.md#scope) in the User's Guide. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP R14B02">>}). +-doc(#{since => <<"OTP R14B02">>}). -callback init(Id, Opts) -> {ok, State} | {ok, State, Priority} when Id :: reference() | term(), Opts :: term(), @@ -138,7 +137,7 @@ If [`Module:on_tc_skip/4`](`c:on_tc_skip/4`) is not exported, common_test will attempt to call `Module:on_tc_skip(TestName, Reason, CTHState)` instead. This is for backwards compatibility. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.3">>}). +-doc(#{since => <<"OTP 19.3">>}). -callback on_tc_skip(SuiteName, TestName, Reason, CTHState) -> NewCTHState when SuiteName :: atom(), TestName :: init_per_suite | end_per_suite | @@ -175,7 +174,7 @@ If [`Module:on_tc_fail/4`](`c:on_tc_fail/4`) is not exported, common_test will attempt to call `Module:on_tc_fail(TestName, Reason, CTHState)` instead. This is for backwards compatibility. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.3">>}). +-doc(#{since => <<"OTP 19.3">>}). -callback on_tc_fail(SuiteName, TestName, Reason, CTHState) -> NewCTHState when SuiteName :: atom(), TestName :: init_per_suite | end_per_suite | @@ -195,7 +194,7 @@ it exists. It behaves the same way as [`post_init_per_suite`](`c:post_init_per_suite/4`), but for function [`end_per_suite`](`c:ct_suite:end_per_suite/1`) instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP R14B02">>}). +-doc(#{since => <<"OTP R14B02">>}). -callback post_end_per_suite(SuiteName, Config, Return, CTHState) -> Result when SuiteName :: atom(), Config :: [{Key,Value}], @@ -215,7 +214,7 @@ if it exists. It behaves the same way as [`pre_init_per_suite`](`c:pre_init_per_suite/3`), but for function [`end_per_suite`](`c:ct_suite:end_per_suite/1`) instead. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP R14B02">>}). +-doc(#{since => <<"OTP R14B02">>}). -callback pre_end_per_suite(SuiteName, EndData, CTHState) -> Result when SuiteName :: atom(), EndData :: Config | SkipOrFail, @@ -241,7 +240,7 @@ common_test will attempt to call `Module:post_end_per_group(GroupName, Config, Return, CTHState)` instead. This is for backwards compatibility. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.3">>}). +-doc(#{since => <<"OTP 19.3">>}). -callback post_end_per_group(SuiteName, GroupName, Config, Return, CTHState) -> Result when SuiteName :: atom(), GroupName :: atom(), @@ -267,7 +266,7 @@ common_test will attempt to call `Module:pre_end_per_group(GroupName, EndData, CTHState)` instead. This is for backwards compatibility. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.3">>}). +-doc(#{since => <<"OTP 19.3">>}). -callback pre_end_per_group(SuiteName, GroupName, EndData, CTHState) -> Result when SuiteName :: atom(), GroupName :: atom(), @@ -293,7 +292,7 @@ exported, common_test will attempt to call `Module:post_end_per_testcase(TestcaseName, Config, Return, CTHState)` instead. This is for backwards compatibility. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.3">>}). +-doc(#{since => <<"OTP 19.3">>}). -callback post_end_per_testcase(SuiteName, TestcaseName, Config, Return, CTHState) -> Result when SuiteName :: atom(), TestcaseName :: atom(), @@ -325,7 +324,7 @@ exported, common_test will attempt to call `Module:pre_end_per_testcase(TestcaseName, EndData, CTHState)` instead. This is for backwards compatibility. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.3">>}). +-doc(#{since => <<"OTP 19.3">>}). -callback pre_end_per_testcase(SuiteName, TestcaseName, EndData, CTHState) -> Result when SuiteName :: atom(), TestcaseName :: atom(), @@ -349,7 +348,7 @@ exported, common_test will attempt to call `Module:post_init_per_testcase(TestcaseName, Config, Return, CTHState)` instead. This is for backwards compatibility. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.3">>}). +-doc(#{since => <<"OTP 19.3">>}). -callback post_init_per_testcase(SuiteName, TestcaseName, Config, Return, CTHState) -> Result when SuiteName :: atom(), TestcaseName :: atom(), @@ -379,7 +378,7 @@ is for backwards compatibility. CTHs cannot be added here right now. That feature may be added in a later release, but it would right now break backwards compatibility. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.3">>}). +-doc(#{since => <<"OTP 19.3">>}). -callback pre_init_per_testcase(SuiteName, TestcaseName, InitData, CTHState) -> Result when SuiteName :: atom(), TestcaseName :: atom(), @@ -406,7 +405,7 @@ common_test will attempt to call `Module:post_init_per_group(GroupName, Config, Return, CTHState)` instead. This is for backwards compatibility. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.3">>}). +-doc(#{since => <<"OTP 19.3">>}). -callback post_init_per_group(SuiteName, GroupName, Config, Return, CTHState) -> Result when SuiteName :: atom(), GroupName :: atom(), @@ -432,7 +431,7 @@ common_test will attempt to call `Module:pre_init_per_group(GroupName, InitData, CTHState)` instead. This is for backwards compatibility. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 19.3">>}). +-doc(#{since => <<"OTP 19.3">>}). -callback pre_init_per_group(SuiteName, GroupName, InitData, CTHState) -> Result when SuiteName :: atom(), GroupName :: atom(), @@ -470,7 +469,7 @@ This function is called only if the CTH is added before or in `init_per_suite`. For details, see section [CTH Scope](ct_hooks_chapter.md#scope) in the User's Guide. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP R14B02">>}). +-doc(#{since => <<"OTP R14B02">>}). -callback post_init_per_suite(SuiteName, Config, Return, CTHState) -> Result when SuiteName :: atom(), Config :: [{Key, Value}], @@ -512,7 +511,7 @@ This function is called only if the CTH is added before `init_per_suite is run`. For details, see section [CTH Scope](ct_hooks_chapter.md#scope) in the User's Guide. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP R14B02">>}). +-doc(#{since => <<"OTP R14B02">>}). -callback pre_init_per_suite(SuiteName, InitData, CTHState) -> Result when SuiteName :: atom(), InitData :: Config | SkipOrFail, @@ -558,7 +557,7 @@ CT start flag, the `c:init/2` function is called first. > [`post_all/3`](`c:post_all/3`) hook function to always be called twice. For > this reason, side effects are best avoided in this callback. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 21.3.8">>}). +-doc(#{since => <<"OTP 21.3.8">>}). -callback post_all(SuiteName, Return, GroupDefs) -> NewReturn when SuiteName :: atom(), Return :: Tests | {skip, Reason}, @@ -622,7 +621,7 @@ first. > [`post_groups/2`](`c:post_groups/2`) hook function to always be called twice. > For this reason, side effects are best avoided in this callback. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP 21.3.8">>}). +-doc(#{since => <<"OTP 21.3.8">>}). -callback post_groups(SuiteName, GroupDefs) -> NewGroupDefs when SuiteName :: atom(), GroupDefs :: [Group], @@ -653,7 +652,7 @@ first. This function is called at the end of a CTH [scope](ct_hooks_chapter.md#scope). The returned term is ignored. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP R14B02">>}). +-doc(#{since => <<"OTP R14B02">>}). -callback terminate(CTHState) -> term() when CTHState :: term(). -optional_callbacks( diff --git a/lib/common_test/src/ct_suite.erl b/lib/common_test/src/ct_suite.erl index 1921a2d15765..98397e83f778 100644 --- a/lib/common_test/src/ct_suite.erl +++ b/lib/common_test/src/ct_suite.erl @@ -4,7 +4,6 @@ The following section describes the mandatory and optional test suite functions that `Common Test` calls during test execution. For more details, see section [Writing Test Suites](write_test_chapter.md) in the User's Guide. """. --moduledoc(#{titles => [{callback,<<"Callback Functions">>}]}). %%------------------------------------------------------------------ %% Test Suite Behaviour %% ------------------------------------------------------------------ @@ -113,7 +112,7 @@ If `{skip, Reason}` is returned, all test cases in the module are skipped and For details on groups, see section [Test Case Groups](write_test_chapter.md#test_case_groups) in the User's Guide. """. --doc(#{title => <<"Callback Functions">>}). +-doc(#{}). -callback all() -> [TestDef :: ct_test_def()] | {skip, Reason :: term()}. @@ -122,7 +121,7 @@ For details on groups, see section Defines test case groups. For details, see section [Test Case Groups](write_test_chapter.md#test_case_groups) in the User's Guide. """. --doc(#{title => <<"Callback Functions">>}). +-doc(#{}). -callback groups() -> [GroupDef :: ct_group_def()]. @@ -158,7 +157,7 @@ For details about the test suite information function, see section [Test Suite Information Function](write_test_chapter.md#suite) in the User's Guide. """. --doc(#{title => <<"Callback Functions">>}). +-doc(#{}). -callback suite() -> [Info :: ct_info()]. @@ -181,7 +180,7 @@ Guide. If this function is defined, then [`Module:end_per_suite/1`](`c:end_per_suite/1`) must also be defined. """. --doc(#{title => <<"Callback Functions">>}). +-doc(#{}). -callback init_per_suite(Config :: ct_config()) -> NewConfig :: ct_config() | {skip, Reason :: term()} | @@ -198,7 +197,7 @@ Guide. If this function is defined, then [`Module:init_per_suite/1`](`c:init_per_suite/1`) must also be defined. """. --doc(#{title => <<"Callback Functions">>}). +-doc(#{}). -callback end_per_suite(Config :: ct_config()) -> term() | {save_config, SaveConfig :: ct_config()}. @@ -237,7 +236,7 @@ For details about the test case group information function, see section [Group Information Function](write_test_chapter.md#group_info) in the User's Guide. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP R15B">>}). +-doc(#{since => <<"OTP R15B">>}). -callback group(GroupName :: ct_groupname()) -> [Info :: ct_info()]. @@ -260,7 +259,7 @@ For information about test case groups, see section If this function is defined, then [`Module:end_per_group/2`](`c:end_per_group/2`) must also be defined. """. --doc(#{title => <<"Callback Functions">>}). +-doc(#{}). -callback init_per_group(GroupName :: ct_groupname(), Config :: ct_config()) -> NewConfig :: ct_config() | {skip, Reason :: term()}. @@ -281,7 +280,7 @@ For details about test case groups, see section If this function is defined, then [`Module:init_per_group/2`](`c:init_per_group/2`) must also be defined. """. --doc(#{title => <<"Callback Functions">>}). +-doc(#{}). -callback end_per_group(GroupName :: ct_groupname(), Config :: ct_config()) -> term() | {return_group_result, Status :: ct_status()}. @@ -301,7 +300,7 @@ printed in the overview log for the suite. If this function is defined, then [`Module:end_per_testcase/2`](`c:end_per_testcase/2`) must also be defined. """. --doc(#{title => <<"Callback Functions">>}). +-doc(#{}). -callback init_per_testcase(TestCase :: ct_testname(), Config :: ct_config()) -> NewConfig :: ct_config() | {fail, Reason :: term()} | @@ -323,7 +322,7 @@ Guide. If this function is defined, then [`Module:init_per_testcase/2`](`c:init_per_testcase/2`) must also be defined. """. --doc(#{title => <<"Callback Functions">>}). +-doc(#{}). -callback end_per_testcase(TestCase :: ct_testname(), Config :: ct_config()) -> term() | {fail, Reason :: term()} | @@ -367,7 +366,7 @@ If the test case function crashes, it is considered failed. For details about test case implementation, see section [Test Cases](write_test_chapter.md#test_cases) in the User's Guide. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP R14B">>}). +-doc(#{since => <<"OTP R14B">>}). -callback 'Testcase'(Config) -> term() | {skip, Reason} | @@ -416,7 +415,7 @@ For details about the test case information function, see section [Test Case Information Function](write_test_chapter.md#info_function) in the User's Guide. """. --doc(#{title => <<"Callback Functions">>,since => <<"OTP R14B">>}). +-doc(#{since => <<"OTP R14B">>}). -callback 'Testcase'() -> [ct_info()]. %% only all/0 is mandatory diff --git a/lib/compiler/test/compile_SUITE_data/ssh.erl b/lib/compiler/test/compile_SUITE_data/ssh.erl index 2bc1bb4621f2..2f2c80d1759b 100644 --- a/lib/compiler/test/compile_SUITE_data/ssh.erl +++ b/lib/compiler/test/compile_SUITE_data/ssh.erl @@ -131,11 +131,6 @@ The directory could be changed with the option - `id_rsa` and `id_rsa.pub` - `id_ecdsa` and `id_ecdsa.pub` """. --moduledoc(#{titles => - [{type,<<"Client Options">>}, - {type,<<"Daemon Options (Server Options)">>}, - {type,<<"Common Options">>}, - {type,<<"Other data types">>}]}). -include("ssh.hrl"). -include("ssh_connect.hrl"). @@ -208,7 +203,7 @@ Opaque data type representing a daemon. Returned by the functions [`daemon/1,2,3`](`daemon/1`). """. --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -opaque daemon_ref() :: pid() . -doc """ Opaque data type representing a channel inside a connection. @@ -216,7 +211,7 @@ 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(#{group => <<"Other data types">>}). -opaque channel_id() :: non_neg_integer(). -doc """ Opaque data type representing a connection between a client and a server @@ -225,7 +220,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(#{group => <<"Other data types">>}). -type connection_ref() :: pid(). % should be -opaque, but that gives problems %%-------------------------------------------------------------------- @@ -429,13 +424,13 @@ close(ConnectionRef) -> %%-------------------------------------------------------------------- %% Description: Retrieves information about a connection. %%--------------------------------------------------------------------- --doc(#{title => <<"Other data types">>,equiv => conn_info_channels/0}). +-doc(#{group => <<"Other data types">>,equiv => conn_info_channels/0}). -type version() :: {protocol_version(), software_version()}. --doc(#{title => <<"Other data types">>,equiv => conn_info_channels/0}). +-doc(#{group => <<"Other data types">>,equiv => conn_info_channels/0}). -type protocol_version() :: {Major::pos_integer(), Minor::non_neg_integer()}. --doc(#{title => <<"Other data types">>,equiv => conn_info_channels/0}). +-doc(#{group => <<"Other data types">>,equiv => conn_info_channels/0}). -type software_version() :: string(). --doc(#{title => <<"Other data types">>,equiv => conn_info_channels/0}). +-doc(#{group => <<"Other data types">>,equiv => conn_info_channels/0}). -type conn_info_algs() :: [{kex, kex_alg()} | {hkey, pubkey_alg()} | {encrypt, cipher_alg()} @@ -453,10 +448,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(#{group => <<"Other data types">>}). -type conn_info_channels() :: [proplists:proplist()]. --doc(#{title => <<"Other data types">>,equiv => conn_info_channels/0}). +-doc(#{group => <<"Other data types">>,equiv => conn_info_channels/0}). -type connection_info_tuple() :: {client_version, version()} | {server_version, version()} @@ -694,7 +689,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(#{group => <<"Other data types">>}). -type daemon_info_tuple() :: {port, inet:port_number()} | {ip, inet:ip_address()} diff --git a/lib/compiler/test/compile_SUITE_data/ssh.hrl b/lib/compiler/test/compile_SUITE_data/ssh.hrl index f78a6e4cea88..05ed725463ec 100644 --- a/lib/compiler/test/compile_SUITE_data/ssh.hrl +++ b/lib/compiler/test/compile_SUITE_data/ssh.hrl @@ -124,14 +124,14 @@ %% Types -type role() :: client | server . --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"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(#{group => <<"Other data types">>}). -type open_socket() :: gen_tcp:socket(). -doc """ @@ -150,13 +150,13 @@ If the subsystems option is not present, the value of default. The option can be set to the empty list if you do not want the daemon to run any subsystems. """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type subsystem_spec() :: {Name::string(), mod_args()} . --doc(#{title => <<"Common Options">>, +-doc(#{group => <<"Common Options">>, equiv => double_algs/1}). -type algs_list() :: list( alg_entry() ). --doc(#{title => <<"Common Options">>, +-doc(#{group => <<"Common Options">>, equiv => double_algs/1}). -type alg_entry() :: {kex, [kex_alg()]} | {public_key, [pubkey_alg()]} @@ -164,7 +164,7 @@ to run any subsystems. | {mac, double_algs(mac_alg())} | {compression, double_algs(compression_alg())} . --doc(#{title => <<"Common Options">>, +-doc(#{group => <<"Common Options">>, equiv => double_algs/1}). -type kex_alg() :: 'curve25519-sha256' | 'curve25519-sha256@libssh.org' | @@ -181,7 +181,7 @@ to run any subsystems. 'diffie-hellman-group1-sha1' . --doc(#{title => <<"Common Options">>, +-doc(#{group => <<"Common Options">>, equiv => double_algs/1}). -type pubkey_alg() :: 'ssh-ed25519' | 'ssh-ed448' | @@ -194,7 +194,7 @@ to run any subsystems. 'ssh-dss' . --doc(#{title => <<"Common Options">>, +-doc(#{group => <<"Common Options">>, equiv => double_algs/1}). -type cipher_alg() :: 'aes256-gcm@openssh.com' | 'aes256-ctr' | @@ -210,7 +210,7 @@ to run any subsystems. '3des-cbc' . --doc(#{title => <<"Common Options">>, +-doc(#{group => <<"Common Options">>, equiv => double_algs/1}). -type mac_alg() :: 'hmac-sha2-512-etm@openssh.com' | 'hmac-sha2-256-etm@openssh.com' | @@ -223,7 +223,7 @@ to run any subsystems. 'AEAD_AES_128_GCM' . --doc(#{title => <<"Common Options">>, +-doc(#{group => <<"Common Options">>, equiv => double_algs/1}). -type compression_alg() :: 'none' | 'zlib' | @@ -268,7 +268,7 @@ time. > you know exactly what you are doing. If you do not understand the values then > you are not supposed to change them. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type double_algs(AlgType) :: list( {client2server,[AlgType]} | {server2client,[AlgType]} ) | [AlgType]. @@ -319,27 +319,27 @@ The example specifies that: For background and more examples see the [User's Guide](configure_algos.md#introduction). """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type modify_algs_list() :: list( {append,algs_list()} | {prepend,algs_list()} | {rm,algs_list()} ) . -type internal_options() :: ssh_options:private_options(). -type socket_options() :: [gen_tcp:connect_option() | gen_tcp:listen_option()]. --doc(#{title => <<"Client Options">>,equiv => client_option/0}). +-doc(#{group => <<"Client Options">>,equiv => client_option/0}). -type client_options() :: [ client_option() ] . --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => daemon_option/0}). -type daemon_options() :: [ daemon_option() ]. --doc(#{title => <<"Common Options">>, +-doc(#{group => <<"Common Options">>, equiv => common_option/0}). -type common_options() :: [ common_option() ]. -doc """ The options above can be used both in clients and in daemons (servers). They are further explained below. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type common_option() :: ssh_file:user_dir_common_option() | profile_common_option() @@ -368,7 +368,7 @@ one server that has the same `ip-address` and `port`. If this property is not explicitly set, it is assumed that the the `ip-address` and `port` uniquely identifies the SSH daemon. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type profile_common_option() :: {profile, atom() }. -doc """ Sets a time-out on a connection when no channels are open. Defaults to @@ -381,9 +381,9 @@ For more information about timeouts, see the [Timeouts section ](hardening.md#timeouts)in the User's Guide [Hardening](hardening.md) chapter. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type max_idle_time_common_option() :: {idle_time, timeout()}. --doc(#{title => <<"Common Options">>, +-doc(#{group => <<"Common Options">>, equiv => limit_time/0}). -type rekey_limit_common_option() :: {rekey_limit, Bytes::limit_bytes() | {Minutes::limit_time(), Bytes::limit_bytes()} @@ -392,10 +392,10 @@ For more information about timeouts, see the Sets a limit for the size of a logged item excluding a header. The unit is bytes and the value defaults to 500. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type max_log_item_len_common_option() :: {max_log_item_len, limit_bytes()} . --doc(#{title => <<"Common Options">>, +-doc(#{group => <<"Common Options">>, equiv => limit_time/0}). -type limit_bytes() :: non_neg_integer() | infinity . % non_neg_integer due to compatibility -doc """ @@ -415,7 +415,7 @@ certain amount of data has been transferred. If the option value is set to `{infinity, infinity}`, no rekeying will be initiated. Note that rekeying initiated by the peer will still be performed. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type limit_time() :: pos_integer() | infinity . -doc """ @@ -440,10 +440,10 @@ where `...` are arguments to `F` as in `m:ssh_client_key_api` and/or `m:ssh_server_key_api`. The `UserOptions` are the options given to [ssh:connect](`connect/3`), [ssh:shell](`shell/1`) or [ssh:daemon](`daemon/2`). """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type key_cb_common_option() :: {key_cb, Module::atom() | {Module::atom(),Opts::[term()]} } . -doc "Provides a fun to implement your own logging or other handling at disconnects.". --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type disconnectfun_common_option() :: {disconnectfun, fun((Reason::term()) -> void | any()) }. -doc """ @@ -451,7 +451,7 @@ Provides a fun to implement your own logging or other action when an unexpected message arrives. If the fun returns `report` the usual info report is issued but if `skip` is returned no report is generated. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type unexpectedfun_common_option() :: {unexpectedfun, fun((Message::term(),{Host::term(),Port::term()}) -> report | skip ) }. -doc """ @@ -465,7 +465,7 @@ The default behaviour is ignore the message. To get a printout for each message with `AlwaysDisplay = true`, use for example `{ssh_msg_debug_fun, fun(_,true,M,_)-> io:format("DEBUG: ~p~n", [M]) end}` """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type ssh_msg_debug_fun_common_option() :: {ssh_msg_debug_fun, fun((ssh:connection_ref(),AlwaysDisplay::boolean(),Msg::binary(),LanguageTag::binary()) -> any()) } . @@ -480,7 +480,7 @@ the ssh software brand and version. The value `{random, Nmin, Nmax}` will make a random string with at least `Nmin` characters and at most `Nmax` characters. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type id_string_common_option() :: {id_string, string() | random | {random,Nmin::pos_integer(),Nmax::pos_integer()} }. -doc """ List of user (client) public key algorithms to try to use. @@ -495,12 +495,12 @@ and current user's public keys. See also the option [`user_dir`](`t:ssh_file:user_dir_common_option/0`) for specifying the path to the user's keys. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type pref_public_key_algs_common_option() :: {pref_public_key_algs, [pubkey_alg()] } . --doc(#{title => <<"Common Options">>, +-doc(#{group => <<"Common Options">>, equiv => double_algs/1}). -type preferred_algorithms_common_option():: {preferred_algorithms, algs_list()}. --doc(#{title => <<"Common Options">>, +-doc(#{group => <<"Common Options">>, equiv => modify_algs_list/0}). -type modify_algorithms_common_option() :: {modify_algorithms, modify_algs_list()}. -doc """ @@ -510,17 +510,17 @@ client shall support and in which order they are tried. Defaults to Note that the client is free to use any order and to exclude methods. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type auth_methods_common_option() :: {auth_methods, string() }. -doc "IP version to use when the host address is specified as `any`.". --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type inet_common_option() :: {inet, inet | inet6} . -doc """ Allows an existing file-descriptor to be used (passed on to the transport protocol). """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type fd_common_option() :: {fd, gen_tcp:socket()} . @@ -528,7 +528,7 @@ protocol). Opaque types that define experimental options that are not to be used in products. """. --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -type opaque_common_options() :: {transport, {atom(),atom(),atom()} } | {vsn, {non_neg_integer(),non_neg_integer()} } @@ -549,7 +549,7 @@ Also note that setting a `t:gen_tcp:connect_option/0` could change the socket in a way that impacts the ssh client's behaviour negatively. You use it on your own risk. """. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type client_option() :: ssh_file:pubkey_passphrase_client_options() | host_accepting_client_options() @@ -561,7 +561,7 @@ risk. | gen_tcp:connect_option() | ?COMMON_OPTION . --doc(#{title => <<"Other data types">>, +-doc(#{group => <<"Other data types">>, equiv => opaque_common_options/0}). -type opaque_client_options() :: {keyboard_interact_fun, fun((Name::iodata(), @@ -572,22 +572,22 @@ risk. )} | opaque_common_options(). --doc(#{title => <<"Client Options">>,equiv => fingerprint/0}). +-doc(#{group => <<"Client Options">>,equiv => fingerprint/0}). -type host_accepting_client_options() :: {silently_accept_hosts, accept_hosts()} | {user_interaction, boolean()} | {save_accepted_host, boolean()} | {quiet_mode, boolean()} . --doc(#{title => <<"Client Options">>,equiv => fingerprint/0}). +-doc(#{group => <<"Client Options">>,equiv => fingerprint/0}). -type accept_hosts() :: boolean() | accept_callback() | {HashAlgoSpec::fp_digest_alg(), accept_callback()}. --doc(#{title => <<"Client Options">>,equiv => fingerprint/0}). +-doc(#{group => <<"Client Options">>,equiv => fingerprint/0}). -type fp_digest_alg() :: 'md5' | crypto:sha1() | crypto:sha2() . --doc(#{title => <<"Client Options">>,equiv => fingerprint/0}). +-doc(#{group => <<"Client Options">>,equiv => fingerprint/0}). -type accept_callback() :: fun((PeerName::string(), fingerprint() ) -> boolean()) % Old style | fun((PeerName::string(), Port::inet:port_number(), fingerprint() ) -> boolean()) % New style . @@ -650,7 +650,7 @@ risk. Defaults to `false` """. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type fingerprint() :: string() | [string()]. -doc """ @@ -661,7 +661,7 @@ risk. option is not given, the user is asked for a password, if the password authentication method is attempted. """. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type authentication_client_options() :: {user, string()} | {password, string()} . @@ -672,7 +672,7 @@ connected server in choosing a group. See [RFC 4419](https://tools.ietf.org/html/rfc4419) for the details. The default value is `{1024, 6144, 8192}`. """. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type diffie_hellman_group_exchange_client_option() :: {dh_gex_limits, {Min::pos_integer(), I::pos_integer(), Max::pos_integer()} } . @@ -683,7 +683,7 @@ in milli-seconds and the default value is `infinity`. See the parameter `Timeout` in `connect/4` for a timeout of the negotiation phase. """. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type connect_timeout_client_option() :: {connect_timeout, timeout()} . -doc """ @@ -696,7 +696,7 @@ extensions. Default value is `true` which is compatible with other implementations not supporting ext-info. """. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type recv_ext_info_client_option() :: {recv_ext_info, boolean()} . @@ -712,7 +712,7 @@ Also note that setting a `t:gen_tcp:listen_option/0` could change the socket in a way that impacts the ssh deamon's behaviour negatively. You use it on your own risk. """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type daemon_option() :: subsystem_daemon_option() | shell_daemon_option() @@ -732,23 +732,23 @@ risk. | gen_tcp:listen_option() | ?COMMON_OPTION . --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => subsystem_spec/0}). -type subsystem_daemon_option() :: {subsystems, subsystem_specs()}. --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => subsystem_spec/0}). -type subsystem_specs() :: [ subsystem_spec() ]. --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => 'shell_fun/2'/0}). -type shell_daemon_option() :: {shell, shell_spec()} . --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => 'shell_fun/2'/0}). -type shell_spec() :: mod_fun_args() | shell_fun() | disabled . --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => 'shell_fun/2'/0}). -type shell_fun() :: 'shell_fun/1'() | 'shell_fun/2'() . --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => 'shell_fun/2'/0}). -type 'shell_fun/1'() :: fun((User::string()) -> pid()) . -doc """ @@ -759,23 +759,23 @@ See the option [`exec-option`](`t:exec_daemon_option/0`) for a description of how the daemon executes shell-requests and exec-requests depending on the shell- and exec-options. """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type 'shell_fun/2'() :: fun((User::string(), PeerAddr::inet:ip_address()) -> pid()). --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => exec_spec/0}). -type exec_daemon_option() :: {exec, exec_spec()} . --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type exec_spec() :: {direct, exec_fun()} | disabled | deprecated_exec_opt(). --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type exec_fun() :: 'exec_fun/1'() | 'exec_fun/2'() | 'exec_fun/3'(). --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => 'exec_fun/3'/0}). -type 'exec_fun/1'() :: fun((Cmd::string()) -> exec_result()) . --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => 'exec_fun/3'/0}). -type 'exec_fun/2'() :: fun((Cmd::string(), User::string()) -> exec_result()) . --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type 'exec_fun/3'() :: fun((Cmd::string(), User::string(), ClientAddr::ip_port()) -> exec_result()) . -doc """ This option changes how the daemon executes exec-requests from clients. The term @@ -847,13 +847,13 @@ implied by the custom CLI. > retained but obey the rules 1-6 above if conflicting. The old and undocumented > style should not be used in new programs. """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type exec_result() :: {ok,Result::term()} | {error,Reason::term()} . -doc """ Old-style exec specification that are kept for compatibility, but should not be used in new programs """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type deprecated_exec_opt() :: fun() | mod_fun_args() . -doc """ @@ -866,20 +866,20 @@ own CLI channel. If `ssh_cli` is set to `no_cli`, the CLI channels like [`shell`](`t:shell_daemon_option/0`) and [`exec`](`t:exec_daemon_option/0`) are disabled and only subsystem channels are allowed. """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type ssh_cli_daemon_option() :: {ssh_cli, mod_args() | no_cli }. -doc """ Enables (`true`) or disables (`false`) the possibility to tunnel a TCP/IP connection out of a [server](`daemon/2`). Disabled per default. """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type tcpip_tunnel_out_daemon_option() :: {tcpip_tunnel_out, boolean()} . -doc """ Enables (`true`) or disables (`false`) the possibility to tunnel a TCP/IP connection in to a [server](`daemon/2`). Disabled per default. """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type tcpip_tunnel_in_daemon_option() :: {tcpip_tunnel_in, boolean()} . -doc """ @@ -892,10 +892,10 @@ extensions. Default value is `true` which is compatible with other implementations not supporting ext-info. """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type send_ext_info_daemon_option() :: {send_ext_info, boolean()} . --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => pwdfun_4/0}). -type authentication_daemon_options() :: ssh_file:system_dir_daemon_option() @@ -907,7 +907,7 @@ supporting ext-info. | {no_auth_needed, boolean()} . --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => pwdfun_4/0}). -type prompt_texts() :: kb_int_tuple() @@ -915,17 +915,17 @@ supporting ext-info. | kb_int_fun_4() . --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => pwdfun_4/0}). -type kb_int_fun_3() :: fun((Peer::ip_port(), User::string(), Service::string()) -> kb_int_tuple()). --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => pwdfun_4/0}). -type kb_int_fun_4() :: fun((Peer::ip_port(), User::string(), Service::string(), State::any()) -> kb_int_tuple()). --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => pwdfun_4/0}). -type kb_int_tuple() :: {Name::string(), Instruction::string(), Prompt::string(), Echo::boolean()}. --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => pwdfun_4/0}). -type pwdfun_2() :: fun((User::string(), Password::string()|pubkey) -> boolean()) . -doc """ @@ -1025,7 +1025,7 @@ supporting ext-info. The default value is `false`. """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type pwdfun_4() :: fun((User::string(), Password::string()|pubkey, PeerAddress::ip_port(), @@ -1033,16 +1033,16 @@ supporting ext-info. boolean() | disconnect | {boolean(),NewState::any()} ) . --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => ssh_moduli_file/0}). -type diffie_hellman_group_exchange_daemon_option() :: {dh_gex_groups, [explicit_group()] | explicit_group_file() | ssh_moduli_file()} | {dh_gex_limits, {Min::pos_integer(), Max::pos_integer()} } . --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => ssh_moduli_file/0}). -type explicit_group() :: {Size::pos_integer(),G::pos_integer(),P::pos_integer()} . --doc(#{title => <<"Daemon Options (Server Options)">>, +-doc(#{group => <<"Daemon Options (Server Options)">>, equiv => ssh_moduli_file/0}). -type explicit_group_file() :: {file,string()} . -doc """ @@ -1078,7 +1078,7 @@ supporting ext-info. See [RFC 4419](https://tools.ietf.org/html/rfc4419) for the function of the Max and Min values. """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type ssh_moduli_file() :: {ssh_moduli_file,string()}. -doc """ @@ -1089,7 +1089,7 @@ For more information about timeouts, see the [Timeouts section ](hardening.md#timeouts)in the User's Guide [Hardening](hardening.md) chapter. """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type max_initial_idle_time_daemon_option() :: {max_initial_idle_time, timeout()} . -doc """ Maximum time in milliseconds for the authentication negotiation. Defaults to @@ -1100,7 +1100,7 @@ For more information about timeouts, see the [Timeouts section ](hardening.md#timeouts)in the User's Guide [Hardening](hardening.md) chapter. """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type negotiation_timeout_daemon_option() :: {negotiation_timeout, timeout()} . -doc """ Maximum time in milliseconds for the first part of the ssh session setup, the @@ -1111,7 +1111,7 @@ For more information about timeouts, see the [Timeouts section ](hardening.md#timeouts)in the User's Guide [Hardening](hardening.md) chapter. """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type hello_timeout_daemon_option() :: {hello_timeout, timeout()} . -doc """ @@ -1160,7 +1160,7 @@ in the User's Guide chapter. maximum packet size that the daemon will accept in channel open requests from the client. The default value is 0. """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type hardening_daemon_options() :: {max_sessions, pos_integer()} | {max_channels, pos_integer()} @@ -1174,23 +1174,23 @@ in the User's Guide chapter. - **`failfun`** - Provides a fun to implement your own logging when a user fails to authenticate. """. --doc(#{title => <<"Daemon Options (Server Options)">>}). +-doc(#{group => <<"Daemon Options (Server Options)">>}). -type callbacks_daemon_options() :: {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(#{group => <<"Other data types">>, equiv => opaque_common_options/0}). -type opaque_daemon_options() :: {infofun, fun()} | opaque_common_options(). --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -type ip_port() :: {inet:ip_address(), inet:port_number()} . --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -type mod_args() :: {Module::atom(), Args::list()} . --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -type mod_fun_args() :: {Module::atom(), Function::atom(), Args::list()} . diff --git a/lib/crypto/src/crypto.erl b/lib/crypto/src/crypto.erl index 98849fbd8097..effaf4e478d5 100644 --- a/lib/crypto/src/crypto.erl +++ b/lib/crypto/src/crypto.erl @@ -148,26 +148,6 @@ end ``` """. --moduledoc(#{titles => - [{function,<<"Cipher API">>}, - {function,<<"Hash API">>}, - {function,<<"MAC API">>}, - {function,<<"Key API">>}, - {function,<<"Sign/Verify API">>}, - {function,<<"Random API">>}, - {function,<<"Utility Functions">>}, - {function,<<"Engine API">>}, - {function,<<"Legacy RSA Encryption API">>}, - {type,<<"Ciphers">>}, - {type,<<"Digests and hash">>}, - {type,<<"Elliptic Curves">>}, - {type,<<"Keys">>}, - {type,<<"Public/Private Keys">>}, - {type,<<"Public Key Ciphers">>}, - {type,<<"Public Key Sign and Verify">>}, - {type,<<"Diffie-Hellman Keys and parameters">>}, - {type,<<"Types for Engines">>}, - {type,<<"Internal data types">>}]}). -export([start/0, stop/0, info/0, info_lib/0, info_fips/0, supports/0, enable_fips_mode/1, version/0, bytes_to_integer/1]). @@ -352,13 +332,13 @@ end %%% Basic -doc "Always `t:binary/0` when used as return value". --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -type key_integer() :: integer() | binary(). % Always binary() when used as return value %%% Keys --doc(#{title => <<"Public/Private Keys">>,equiv => rsa_params()}). +-doc(#{group => <<"Public/Private Keys">>,equiv => rsa_params()}). -type rsa_public() :: [key_integer()] . % [E, N] --doc(#{title => <<"Public/Private Keys">>,equiv => rsa_params()}). +-doc(#{group => <<"Public/Private Keys">>,equiv => rsa_params()}). -type rsa_private() :: [key_integer()] . % [E, N, D] | [E, N, D, P1, P2, E1, E2, C] -doc """ ```text @@ -375,10 +355,10 @@ the calculation faster. P1 and P2 are first and second prime factors. E1 and E2 are first and second exponents. C is the CRT coefficient. The terminology is taken from [RFC 3447](http://www.ietf.org/rfc/rfc3447.txt). """. --doc(#{title => <<"Public/Private Keys">>}). +-doc(#{group => <<"Public/Private Keys">>}). -type rsa_params() :: {ModulusSizeInBits::integer(), PublicExponent::key_integer()} . --doc(#{title => <<"Public/Private Keys">>,equiv => dss_private()}). +-doc(#{group => <<"Public/Private Keys">>,equiv => dss_private()}). -type dss_public() :: [key_integer()] . % [P, Q, G, Y] -doc """ ```text @@ -393,24 +373,24 @@ dss_private() = [P, Q, G, X] Where P, Q and G are the dss parameters and X is the private key. """. --doc(#{title => <<"Public/Private Keys">>}). +-doc(#{group => <<"Public/Private Keys">>}). -type dss_private() :: [key_integer()] . % [P, Q, G, X] --doc(#{title => <<"Public/Private Keys">>,equiv => ecdsa_params()}). +-doc(#{group => <<"Public/Private Keys">>,equiv => ecdsa_params()}). -type ecdsa_public() :: key_integer() . --doc(#{title => <<"Public/Private Keys">>,equiv => ecdsa_params()}). +-doc(#{group => <<"Public/Private Keys">>,equiv => ecdsa_params()}). -type ecdsa_private() :: key_integer() . --doc(#{title => <<"Public/Private Keys">>}). +-doc(#{group => <<"Public/Private Keys">>}). -type ecdsa_params() :: ec_named_curve() | ec_explicit_curve() . --doc(#{title => <<"Public/Private Keys">>,equiv => eddsa_params()}). +-doc(#{group => <<"Public/Private Keys">>,equiv => eddsa_params()}). -type eddsa_public() :: key_integer() . --doc(#{title => <<"Public/Private Keys">>,equiv => eddsa_params()}). +-doc(#{group => <<"Public/Private Keys">>,equiv => eddsa_params()}). -type eddsa_private() :: key_integer() . --doc(#{title => <<"Public/Private Keys">>}). +-doc(#{group => <<"Public/Private Keys">>}). -type eddsa_params() :: edwards_curve_ed() . --doc(#{title => <<"Public/Private Keys">>,equiv => srp_private()}). +-doc(#{group => <<"Public/Private Keys">>,equiv => srp_private()}). -type srp_public() :: key_integer() . -doc """ ```text @@ -425,21 +405,21 @@ srp_private() = key_integer() Where is `a` or `b` from [SRP design](http://srp.stanford.edu/design.html) """. --doc(#{title => <<"Public/Private Keys">>}). +-doc(#{group => <<"Public/Private Keys">>}). -type srp_private() :: key_integer() . --doc(#{title => <<"Public/Private Keys">>, +-doc(#{group => <<"Public/Private Keys">>, equiv => srp_host_comp_params()}). -type srp_gen_params() :: {user,srp_user_gen_params()} | {host,srp_host_gen_params()}. --doc(#{title => <<"Public/Private Keys">>, +-doc(#{group => <<"Public/Private Keys">>, equiv => srp_host_comp_params()}). -type srp_comp_params() :: {user,srp_user_comp_params()} | {host,srp_host_comp_params()}. --doc(#{title => <<"Public/Private Keys">>, +-doc(#{group => <<"Public/Private Keys">>, equiv => srp_host_comp_params()}). -type srp_user_gen_params() :: list(binary() | atom() | list()) . --doc(#{title => <<"Public/Private Keys">>, +-doc(#{group => <<"Public/Private Keys">>, equiv => srp_host_comp_params()}). -type srp_host_gen_params() :: list(binary() | atom() | list()) . --doc(#{title => <<"Public/Private Keys">>, +-doc(#{group => <<"Public/Private Keys">>, equiv => srp_host_comp_params()}). -type srp_user_comp_params() :: list(binary() | atom()) . -doc """ @@ -447,35 +427,35 @@ Where Verifier is `v`, Generator is `g` and Prime is` N`, DerivedKey is `X`, and Scrambler is `u` (optional will be generated if not provided) from [SRP design](http://srp.stanford.edu/design.html) Version = '3' | '6' | '6a' """. --doc(#{title => <<"Public/Private Keys">>}). +-doc(#{group => <<"Public/Private Keys">>}). -type srp_host_comp_params() :: list(binary() | atom()) . --doc(#{title => <<"Diffie-Hellman Keys and parameters">>, +-doc(#{group => <<"Diffie-Hellman Keys and parameters">>, equiv => dh_private()}). -type dh_public() :: key_integer() . --doc(#{title => <<"Diffie-Hellman Keys and parameters">>}). +-doc(#{group => <<"Diffie-Hellman Keys and parameters">>}). -type dh_private() :: key_integer() . -doc """ ```text dh_params() = [P, G] | [P, G, PrivateKeyBitLength] ``` """. --doc(#{title => <<"Diffie-Hellman Keys and parameters">>}). +-doc(#{group => <<"Diffie-Hellman Keys and parameters">>}). -type dh_params() :: [key_integer()] . % [P, G] | [P, G, PrivateKeyBitLength] --doc(#{title => <<"Diffie-Hellman Keys and parameters">>, +-doc(#{group => <<"Diffie-Hellman Keys and parameters">>, equiv => ecdh_params()}). -type ecdh_public() :: key_integer() . --doc(#{title => <<"Diffie-Hellman Keys and parameters">>, +-doc(#{group => <<"Diffie-Hellman Keys and parameters">>, equiv => ecdh_params()}). -type ecdh_private() :: key_integer() . --doc(#{title => <<"Diffie-Hellman Keys and parameters">>}). +-doc(#{group => <<"Diffie-Hellman Keys and parameters">>}). -type ecdh_params() :: ec_named_curve() | edwards_curve_dh() | ec_explicit_curve() . %%% Curves --doc(#{title => <<"Elliptic Curves">>,equiv => ec_curve()}). +-doc(#{group => <<"Elliptic Curves">>,equiv => ec_curve()}). -type ec_explicit_curve() :: {Field :: ec_field(), Curve :: ec_curve(), BasePoint :: binary(), @@ -485,27 +465,27 @@ dh_params() = [P, G] | [P, G, PrivateKeyBitLength] } . -doc "Parametric curve definition.". --doc(#{title => <<"Elliptic Curves">>}). +-doc(#{group => <<"Elliptic Curves">>}). -type ec_curve() :: {A :: binary(), B :: binary(), Seed :: none | binary() } . --doc(#{title => <<"Elliptic Curves">>,equiv => ec_curve()}). +-doc(#{group => <<"Elliptic Curves">>,equiv => ec_curve()}). -type ec_field() :: ec_prime_field() | ec_characteristic_two_field() . --doc(#{title => <<"Elliptic Curves">>,equiv => ec_basis()}). +-doc(#{group => <<"Elliptic Curves">>,equiv => ec_basis()}). -type ec_prime_field() :: {prime_field, Prime :: integer()} . --doc(#{title => <<"Elliptic Curves">>,equiv => ec_basis()}). +-doc(#{group => <<"Elliptic Curves">>,equiv => ec_basis()}). -type ec_characteristic_two_field() :: {characteristic_two_field, M :: integer(), Basis :: ec_basis()} . -doc "Curve definition details.". --doc(#{title => <<"Elliptic Curves">>}). +-doc(#{group => <<"Elliptic Curves">>}). -type ec_basis() :: {tpbasis, K :: non_neg_integer()} | {ppbasis, K1 :: non_neg_integer(), K2 :: non_neg_integer(), K3 :: non_neg_integer()} | onbasis . --doc(#{title => <<"Elliptic Curves">>,equiv => edwards_curve_ed()}). +-doc(#{group => <<"Elliptic Curves">>,equiv => edwards_curve_ed()}). -type ec_named_curve() :: brainpoolP160r1 | brainpoolP160t1 | brainpoolP192r1 @@ -591,23 +571,23 @@ dh_params() = [P, G] | [P, G, PrivateKeyBitLength] | wtls9 . --doc(#{title => <<"Elliptic Curves">>,equiv => edwards_curve_ed()}). +-doc(#{group => <<"Elliptic Curves">>,equiv => edwards_curve_ed()}). -type edwards_curve_dh() :: x25519 | x448 . --doc(#{title => <<"Utility functions">>}). +-doc(#{group => <<"Utility functions">>}). -doc "Note that some curves are disabled if FIPS is enabled.". --doc(#{title => <<"Elliptic Curves">>}). +-doc(#{group => <<"Elliptic Curves">>}). -type edwards_curve_ed() :: ed25519 | ed448 . %%%---------------------------------------------------------------- %%% New cipher schema %%% --doc(#{title => <<"Ciphers">>}). +-doc(#{group => <<"Ciphers">>}). -type cipher() :: cipher_no_iv() | cipher_iv() | cipher_aead() . --doc(#{title => <<"Ciphers">>}). +-doc(#{group => <<"Ciphers">>}). -type cipher_no_iv() :: aes_128_ecb | aes_192_ecb | aes_256_ecb @@ -618,7 +598,7 @@ dh_params() = [P, G] | [P, G, PrivateKeyBitLength] | sm4_ecb | rc4 . --doc(#{title => <<"Ciphers">>}). +-doc(#{group => <<"Ciphers">>}). -type cipher_iv() :: aes_128_cbc | aes_192_cbc | aes_256_cbc @@ -666,7 +646,7 @@ Ciphers known by the CRYPTO application. Note that this list might be reduced if the underlying libcrypto does not support all of them. """. --doc(#{title => <<"Ciphers">>}). +-doc(#{group => <<"Ciphers">>}). -type cipher_aead() :: aes_128_ccm | aes_192_ccm | aes_256_ccm @@ -685,29 +665,29 @@ support all of them. %%%---------------------------------------------------------------- --doc(#{title => <<"Digests and hash">>}). +-doc(#{group => <<"Digests and hash">>}). -type rsa_digest_type() :: sha1() | sha2() | md5 | ripemd160 . --doc(#{title => <<"Digests and hash">>}). +-doc(#{group => <<"Digests and hash">>}). -type dss_digest_type() :: sha1() | sha2() . --doc(#{title => <<"Digests and hash">>}). +-doc(#{group => <<"Digests and hash">>}). -type ecdsa_digest_type() :: sha1() | sha2() . --doc(#{title => <<"Digests and hash">>,equiv => blake2()}). +-doc(#{group => <<"Digests and hash">>,equiv => blake2()}). -type sha1() :: sha . --doc(#{title => <<"Digests and hash">>,equiv => blake2()}). +-doc(#{group => <<"Digests and hash">>,equiv => blake2()}). -type sha2() :: sha224 | sha256 | sha384 | sha512 . --doc(#{title => <<"Digests and hash">>,equiv => blake2()}). +-doc(#{group => <<"Digests and hash">>,equiv => blake2()}). -type sha3() :: sha3_224 | sha3_256 | sha3_384 | sha3_512 . --doc(#{title => <<"Digests and hash">>,equiv => blake2()}). +-doc(#{group => <<"Digests and hash">>,equiv => blake2()}). -type sha3_xof() :: shake128 | shake256 . --doc(#{title => <<"Digests and hash">>}). +-doc(#{group => <<"Digests and hash">>}). -type blake2() :: blake2b | blake2s . -doc """ The `t:compatibility_only_hash/0` algorithms are recommended only for compatibility with existing applications. """. --doc(#{title => <<"Digests and hash">>}). +-doc(#{group => <<"Digests and hash">>}). -type compatibility_only_hash() :: md5 | md4 . -type crypto_integer() :: binary() | integer(). @@ -796,7 +776,7 @@ format_error({Ex, {C_file,C_line}, Msg}, [{_M,_F,_Args,Opts} | _CallStack]) when end end. --doc(#{title => <<"Deprecated API">>}). +-doc(#{group => <<"Deprecated API">>}). -doc """ Use [`application:start(crypto)`](`application:start/1`) instead. @@ -810,7 +790,7 @@ Use [`application:start(crypto)`](`application:start/1`) instead. start() -> application:start(crypto). --doc(#{title => <<"Deprecated API">>}). +-doc(#{group => <<"Deprecated API">>}). -doc "Use [`application:stop(crypto)`](`application:stop/1`) instead.". -spec stop() -> ok | {error, Reason::term()}. stop() -> @@ -871,7 +851,7 @@ algorithms. -define(CURVES, '$curves$'). --doc(#{title => <<"Utility Functions">>}). +-doc(#{group => <<"Utility Functions">>}). supports(hashs) -> hash_algorithms(); supports(public_keys) -> pubkey_algorithms(); supports(ciphers) -> add_cipher_aliases(cipher_algorithms()); @@ -879,7 +859,7 @@ supports(macs) -> mac_algorithms(); supports(curves) -> curve_algorithms(); supports(rsa_opts) -> rsa_opts_algorithms(). --doc(#{title => <<"Utility Functions">>}). +-doc(#{group => <<"Utility Functions">>}). -doc """ Get the name and version of the libraries used by crypto. @@ -904,7 +884,7 @@ version. VerStr :: binary() . info_lib() -> ?nif_stub. --doc(#{title => <<"Utility Functions">>}). +-doc(#{group => <<"Utility Functions">>}). -doc """ Get information about crypto and the OpenSSL backend. @@ -927,7 +907,7 @@ Example: More association types than documented may be present in the map. Some of the associations (like fips) may be absent if not supported. """. --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 24.2">>}). -spec info() -> #{compile_type := normal | debug | valgrind | asan, cryptolib_version_compiled := string() | undefined, @@ -960,7 +940,7 @@ about how to enable FIPS mode. > exception `error:notsup`. Check [supports(ciphers)](`supports/1`) that in FIPS > mode returns the restricted list of available algorithms. """. --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 20.0">>}). -spec info_fips() -> not_supported | not_enabled | enabled. @@ -977,7 +957,7 @@ option `--enable-fips`, and the underlying libcrypto must also support FIPS. See also `info_fips/0`. """. --doc(#{title => <<"Deprecated API">>, +-doc(#{group => <<"Deprecated API">>, since => <<"OTP 21.1">>}). -spec enable_fips_mode(Enable) -> Result when Enable :: boolean(), Result :: boolean(). @@ -986,14 +966,14 @@ enable_fips_mode(Enable) -> enable_fips_mode_nif(_) -> ?nif_stub. --doc(#{title => <<"MAC API">>}). +-doc(#{group => <<"MAC API">>}). -doc """ PKCS #5 PBKDF2 (Password-Based Key Derivation Function 2) in combination with HMAC. Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 24.2">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 24.2">>}). -spec pbkdf2_hmac(Digest, Pass, Salt, Iter, KeyLen) -> Result when Digest :: sha | sha224 | sha256 | sha384 | sha512, Pass :: binary(), @@ -1012,9 +992,9 @@ pbkdf2_hmac_nif(_, _, _, _, _) -> ?nif_stub. %%% %%%================================================================ --doc(#{title => <<"Digests and hash">>}). +-doc(#{group => <<"Digests and hash">>}). -type hash_algorithm() :: sha1() | sha2() | sha3() | sha3_xof() | blake2() | ripemd160 | sm3 | compatibility_only_hash() . --doc(#{title => <<"Digests and hash">>}). +-doc(#{group => <<"Digests and hash">>}). -type hash_xof_algorithm() :: sha3_xof() . -doc """ @@ -1025,7 +1005,7 @@ properties of the hash algorithm in question. For a list of supported hash algorithms, see [supports(hashs)](`supports/1`). """. --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 22.0">>}). -spec hash_info(Type) -> Result when Type :: hash_algorithm(), @@ -1043,7 +1023,7 @@ Argument `Type` is the digest type and argument `Data` is the full message. Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"Hash API">>, +-doc(#{group => <<"Hash API">>, since => <<"OTP R15B02">>}). -spec hash(Type, Data) -> Digest when Type :: hash_algorithm(), Data :: iodata(), @@ -1064,7 +1044,7 @@ Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. May raise exception `error:notsup` in case the chosen `Type` is not supported by the underlying libcrypto implementation. """. --doc(#{title => <<"Hash API">>, +-doc(#{group => <<"Hash API">>, since => <<"OTP 26.0">>}). -spec hash_xof(Type, Data, Length) -> Digest when Type :: hash_xof_algorithm(), Data :: iodata(), @@ -1074,7 +1054,7 @@ hash_xof(Type, Data, Length) -> Data1 = iolist_to_binary(Data), hash_xof(Type, Data1, erlang:byte_size(Data1), Length). --doc(#{title => <<"Internal data types">>,equiv => mac_state()}). +-doc(#{group => <<"Internal data types">>,equiv => mac_state()}). -opaque hash_state() :: reference(). -doc """ @@ -1085,7 +1065,7 @@ used as argument to `hash_update/2`. Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"Hash API">>, +-doc(#{group => <<"Hash API">>, since => <<"OTP R15B02">>}). -spec hash_init(Type) -> State when Type :: hash_algorithm(), State :: hash_state(). @@ -1105,7 +1085,7 @@ Returns `NewState` that must be passed into the next call to `hash_update/2` or Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"Hash API">>, +-doc(#{group => <<"Hash API">>, since => <<"OTP R15B02">>}). -spec hash_update(State, Data) -> NewState when State :: hash_state(), NewState :: hash_state(), @@ -1124,7 +1104,7 @@ the type of hash function used to generate it. Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"Hash API">>, +-doc(#{group => <<"Hash API">>, since => <<"OTP R15B02">>}). -spec hash_final(State) -> Digest when State :: hash_state(), Digest :: binary(). @@ -1144,10 +1124,10 @@ hash_final_xof(State, Length) -> %%% %%%================================================================ --doc(#{title => <<"Digests and hash">>}). +-doc(#{group => <<"Digests and hash">>}). -type hmac_hash_algorithm() :: sha1() | sha2() | sha3() | sm3 | compatibility_only_hash(). --doc(#{title => <<"Digests and hash">>}). +-doc(#{group => <<"Digests and hash">>}). -type cmac_cipher_algorithm() :: aes_128_cbc | aes_192_cbc | aes_256_cbc | aes_cbc | blowfish_cbc | des_cbc | des_ede3_cbc @@ -1164,7 +1144,7 @@ Same as [`mac(Type, undefined, Key, Data)`](`mac/4`). Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"MAC API">>, +-doc(#{group => <<"MAC API">>, since => <<"OTP 22.1">>}). -spec mac(Type :: poly1305, Key, Data) -> Mac when Key :: iodata(), @@ -1202,7 +1182,7 @@ the User's Guide. Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"MAC API">>, +-doc(#{group => <<"MAC API">>, since => <<"OTP 22.1">>}). -spec mac(Type, SubType, Key, Data) -> Mac when Type :: hmac | cmac | poly1305, @@ -1223,7 +1203,7 @@ Same as [`macN(Type, undefined, Key, Data, MacLength)`](`macN/5`). Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"MAC API">>, +-doc(#{group => <<"MAC API">>, since => <<"OTP 22.1">>}). -spec macN(Type :: poly1305, Key, Data, MacLength) -> Mac when Key :: iodata(), @@ -1247,7 +1227,7 @@ The max `MacLength` is documented in [Algorithm Details](algorithm_details.md#message-authentication-codes-macs) in the User's Guide. """. --doc(#{title => <<"MAC API">>, +-doc(#{group => <<"MAC API">>, since => <<"OTP 22.1">>}). -spec macN(Type, SubType, Key, Data, MacLength) -> Mac when Type :: hmac | cmac | poly1305, @@ -1268,7 +1248,7 @@ macN(Type, SubType, Key, Data, MacLength) -> Contexts with an internal state that should not be manipulated but passed between function calls. """. --doc(#{title => <<"Internal data types">>}). +-doc(#{group => <<"Internal data types">>}). -opaque mac_state() :: reference() . -doc """ @@ -1278,7 +1258,7 @@ Same as [`mac_init(Type, undefined, Key)`](`mac_init/3`). Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"MAC API">>, +-doc(#{group => <<"MAC API">>, since => <<"OTP 22.1">>}). -spec mac_init(Type :: poly1305, Key) -> State when Key :: iodata(), @@ -1316,7 +1296,7 @@ Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. See [examples in the User's Guide.](new_api.md#example-of-mac_init-mac_update-and-mac_final) """. --doc(#{title => <<"MAC API">>, +-doc(#{group => <<"MAC API">>, since => <<"OTP 22.1">>}). -spec mac_init(Type, SubType, Key) -> State when Type :: hmac | cmac | poly1305, @@ -1342,7 +1322,7 @@ old states. Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"MAC API">>, +-doc(#{group => <<"MAC API">>, since => <<"OTP 22.1">>}). -spec mac_update(State0, Data) -> State when Data :: iodata(), @@ -1366,7 +1346,7 @@ the User's Guide. Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"MAC API">>, +-doc(#{group => <<"MAC API">>, since => <<"OTP 22.1">>}). -spec mac_final(State) -> Mac when State :: mac_state(), @@ -1390,7 +1370,7 @@ the User's Guide. Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"MAC API">>, +-doc(#{group => <<"MAC API">>, since => <<"OTP 22.1">>}). -spec mac_finalN(State, MacLength) -> Mac when State :: mac_state(), @@ -1439,7 +1419,7 @@ support and possibly other properties of the cipher algorithm in question. For a list of supported cipher algorithms, see [supports(ciphers)](`supports/1`). """. --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 22.0">>}). -spec cipher_info(Type) -> Result when Type :: cipher(), @@ -1494,21 +1474,21 @@ cipher_info(Type) -> %%% %%%================================================================ --doc(#{title => <<"Internal data types">>,equiv => mac_state()}). +-doc(#{group => <<"Internal data types">>,equiv => mac_state()}). -opaque crypto_state() :: reference() . --doc(#{title => <<"Ciphers">>,equiv => crypto_opt()}). +-doc(#{group => <<"Ciphers">>,equiv => crypto_opt()}). -type crypto_opts() :: boolean() | [ crypto_opt() ] . -doc "Selects encryption (`{encrypt,true}`) or decryption (`{encrypt,false}`).". --doc(#{title => <<"Ciphers">>}). +-doc(#{group => <<"Ciphers">>}). -type crypto_opt() :: {encrypt,boolean()} | {padding, padding()} . -doc """ This option handles padding in the last block. If not set, no padding is done and any bytes in the last unfilled block is silently discarded. """. --doc(#{title => <<"Ciphers">>}). +-doc(#{group => <<"Ciphers">>}). -type padding() :: cryptolib_padding() | otp_padding(). -doc """ The `cryptolib_padding` are paddings that may be present in the underlying @@ -1517,10 +1497,10 @@ cryptolib linked to the Erlang/OTP crypto app. For OpenSSL, see the [OpenSSL documentation](https://openssl.org). and find `EVP_CIPHER_CTX_set_padding()` in cryptolib for your linked version. """. --doc(#{title => <<"Ciphers">>}). +-doc(#{group => <<"Ciphers">>}). -type cryptolib_padding() :: none | pkcs_padding . -doc "Erlang/OTP adds a either padding of zeroes or padding with random bytes.". --doc(#{title => <<"Ciphers">>}). +-doc(#{group => <<"Ciphers">>}). -type otp_padding() :: zero | random . @@ -1539,7 +1519,7 @@ intended for ciphers without an IV (nounce). Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"Cipher API">>, +-doc(#{group => <<"Cipher API">>, since => <<"OTP 22.0">>}). -spec crypto_init(Cipher, Key, FlagOrOptions) -> State when Cipher :: cipher_no_iv(), @@ -1588,7 +1568,7 @@ Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. See [examples in the User's Guide.](new_api.md#examples-of-crypto_init-4-and-crypto_update-2) """. --doc(#{title => <<"Cipher API">>, +-doc(#{group => <<"Cipher API">>, since => <<"OTP 22.0">>}). -spec crypto_init(Cipher, Key, IV, FlagOrOptions) -> State when Cipher :: cipher_iv(), @@ -1619,7 +1599,7 @@ Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. See [examples in the User's Guide.](new_api.md#examples-of-crypto_init-4-and-crypto_update-2) """. --doc(#{title => <<"Cipher API">>, +-doc(#{group => <<"Cipher API">>, since => <<"OTP 22.0">>}). -spec crypto_update(State, Data) -> Result when State :: crypto_state(), @@ -1644,7 +1624,7 @@ The data returned from this function may be empty if no padding was enabled in Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"Cipher API">>, +-doc(#{group => <<"Cipher API">>, since => <<"OTP 23.0">>}). -spec crypto_final(State) -> FinalResult when State :: crypto_state(), @@ -1673,7 +1653,7 @@ The information returned is a map, which currently contains at least: Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"Cipher API">>, +-doc(#{group => <<"Cipher API">>, since => <<"OTP 23.0">>}). -spec crypto_get_data(State) -> Result when State :: crypto_state(), @@ -1694,7 +1674,7 @@ As `crypto_one_time/5` but for ciphers without IVs. Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"Cipher API">>, +-doc(#{group => <<"Cipher API">>, since => <<"OTP 22.0">>}). -spec crypto_one_time(Cipher, Key, Data, FlagOrOptions) -> Result @@ -1723,7 +1703,7 @@ Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. See [examples in the User's Guide.](new_api.md#example-of-crypto_one_time-5) """. --doc(#{title => <<"Cipher API">>, +-doc(#{group => <<"Cipher API">>, since => <<"OTP 22.0">>}). -spec crypto_one_time(Cipher, Key, IV, Data, FlagOrOptions) -> Result @@ -1741,7 +1721,7 @@ crypto_one_time(Cipher, Key, IV, Data, FlagOrOptions) -> %%%---------------------------------------------------------------- -doc(#{equiv => crypto_one_time_aead/7}). --doc(#{title => <<"Cipher API">>, +-doc(#{group => <<"Cipher API">>, since => <<"OTP 22.0">>}). -spec crypto_one_time_aead(Cipher, Key, IV, InText, AAD, EncFlag::true) -> Result @@ -1782,7 +1762,7 @@ Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. See [examples in the User's Guide.](new_api.md#example-of-crypto_one_time_aead-6) """. --doc(#{title => <<"Cipher API">>, +-doc(#{group => <<"Cipher API">>, since => <<"OTP 22.0">>}). -spec crypto_one_time_aead(Cipher, Key, IV, InText, AAD, TagOrTagLength, EncFlag) -> Result @@ -1832,7 +1812,7 @@ Similar to 'crypto_one_time_aead/7' but only does the initialization part, returns a handle that can be used with 'crypto_one_time_aead/4' serveral times. """). --doc(#{title => <<"Cipher API">>, +-doc(#{group => <<"Cipher API">>, since => <<"OTP 28.0">>}). -spec crypto_one_time_aead_init(Cipher, Key, TagLength, EncFlag) -> Result when Cipher :: cipher_aead(), @@ -1855,7 +1835,7 @@ Similar to 'crypto_one_time_aead/7' but uses the handle from 'crypto_one_time_ae Appends the tag of the specified 'TagLength' to the end of the encrypted data, when doing encryption. Strips the tag from the end of 'InText' and verifies it when doing decryption. """). --doc(#{title => <<"Cipher API">>, +-doc(#{group => <<"Cipher API">>, since => <<"OTP 28.0">>}). -spec crypto_one_time_aead(State, IV, InText, AAD) -> Result @@ -1996,7 +1976,7 @@ from OpenSSL. May raise exception `error:low_entropy` in case the random generator failed due to lack of secure "randomness". """. --doc(#{title => <<"Random API">>, +-doc(#{group => <<"Random API">>, since => <<"OTP R14B03">>}). -spec strong_rand_bytes(N::non_neg_integer()) -> binary(). strong_rand_bytes(Bytes) -> @@ -2027,7 +2007,7 @@ _IntegerValue = rand:uniform(42), % [1; 42] _FloatValue = rand:uniform(). % [0.0; 1.0[ ``` """. --doc(#{title => <<"Random API">>, +-doc(#{group => <<"Random API">>, since => <<"OTP 20.0">>}). -spec rand_seed() -> rand:state(). rand_seed() -> @@ -2051,7 +2031,7 @@ to lack of secure "randomness". > The only supported usage is to generate one distinct random sequence from this > start state. """. --doc(#{title => <<"Random API">>, +-doc(#{group => <<"Random API">>, since => <<"OTP 20.0">>}). -spec rand_seed_s() -> rand:state(). rand_seed_s() -> @@ -2076,7 +2056,7 @@ _IntegerValue = rand:uniform(42), % [1; 42] _FloatValue = rand:uniform(). % [0.0; 1.0[ ``` """. --doc(#{title => <<"Random API">>, +-doc(#{group => <<"Random API">>, since => <<"OTP 21.0">>}). -spec rand_seed_alg(Alg :: atom()) -> {rand:alg_handler(), @@ -2102,7 +2082,7 @@ IntegerValue = rand:uniform(42), % Same values FloatValue = rand:uniform(). % again ``` """. --doc(#{title => <<"Random API">>, +-doc(#{group => <<"Random API">>, since => <<"OTP-22.0">>}). -spec rand_seed_alg(Alg :: atom(), Seed :: term()) -> {rand:alg_handler(), @@ -2113,7 +2093,7 @@ rand_seed_alg(Alg, Seed) -> -define(CRYPTO_CACHE_BITS, 56). -define(CRYPTO_AES_BITS, 58). --doc(#{title => <<"Random API">>}). +-doc(#{group => <<"Random API">>}). -doc """ Create a state object for [random number generation](`m:rand`), in order to generate cryptographically strongly random numbers. @@ -2184,7 +2164,7 @@ Numbers are generated in batches and cached for speed reasons. The cache size can be changed from its default value using the [crypto app's ](crypto_app.md)configuration parameter `rand_cache_size`. """. --doc(#{title => <<"Random API">>, +-doc(#{group => <<"Random API">>, since => <<"OTP 22.0">>}). -spec rand_seed_alg_s(Alg :: atom(), Seed :: term()) -> {rand:alg_handler(), @@ -2376,7 +2356,7 @@ strong_rand_float() -> WholeRange = strong_rand_range(1 bsl 53), ?HALF_DBL_EPSILON * bytes_to_integer(WholeRange). --doc(#{title => <<"Random API">>}). +-doc(#{group => <<"Random API">>}). -doc """ Generate a random integer number. @@ -2421,7 +2401,7 @@ This calls the RAND_seed function from openssl. Only use this if the system you are running on does not have enough "randomness" built in. Normally this is when `strong_rand_bytes/1` raises `error:low_entropy`. """. --doc(#{title => <<"Random API">>, +-doc(#{group => <<"Random API">>, since => <<"OTP 17.0">>}). -spec rand_seed(binary()) -> ok. rand_seed(Seed) when is_binary(Seed) -> @@ -2435,14 +2415,14 @@ rand_seed_nif(_Seed) -> ?nif_stub. %%% %%%================================================================ -doc "Algorithms for sign and verify.". --doc(#{title => <<"Public Key Sign and Verify">>}). +-doc(#{group => <<"Public Key Sign and Verify">>}). -type pk_sign_verify_algs() :: rsa | dss | ecdsa | eddsa . --doc(#{title => <<"Public Key Sign and Verify">>, +-doc(#{group => <<"Public Key Sign and Verify">>, equiv => rsa_sign_verify_padding()}). -type pk_sign_verify_opts() :: [ rsa_sign_verify_opt() ] . --doc(#{title => <<"Public Key Sign and Verify">>, +-doc(#{group => <<"Public Key Sign and Verify">>, equiv => rsa_sign_verify_padding()}). -type rsa_sign_verify_opt() :: {rsa_padding, rsa_sign_verify_padding()} | {rsa_pss_saltlen, integer()} @@ -2458,7 +2438,7 @@ Options for sign and verify. > The exact set of options and there syntax _may_ be changed without prior > notice. """. --doc(#{title => <<"Public Key Sign and Verify">>}). +-doc(#{group => <<"Public Key Sign and Verify">>}). -type rsa_sign_verify_padding() :: rsa_pkcs1_padding | rsa_pkcs1_pss_padding | rsa_x931_padding | rsa_no_padding . @@ -2467,7 +2447,7 @@ Options for sign and verify. %%%---------------------------------------------------------------- %%% Sign --doc(#{title => <<"Sign/Verify API">>, +-doc(#{group => <<"Sign/Verify API">>, since => <<"OTP R16B01">>}). -doc(#{equiv => sign/5}). -spec sign(Algorithm, DigestType, Msg, Key) @@ -2501,7 +2481,7 @@ Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. See also `public_key:sign/3`. """. --doc(#{title => <<"Sign/Verify API">>, +-doc(#{group => <<"Sign/Verify API">>, since => <<"OTP 20.1">>}). -spec sign(Algorithm, DigestType, Msg, Key, Options) -> Signature @@ -2531,7 +2511,7 @@ pkey_sign_nif(_Algorithm, _Type, _Digest, _Key, _Options) -> ?nif_stub. %%% Verify -doc(#{equiv => verify/6}). --doc(#{title => <<"Sign/Verify API">>, +-doc(#{group => <<"Sign/Verify API">>, since => <<"OTP R16B01">>}). -spec verify(Algorithm, DigestType, Msg, Signature, Key) -> Result @@ -2564,7 +2544,7 @@ Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. See also `public_key:verify/4`. """. --doc(#{title => <<"Sign/Verify API">>, +-doc(#{group => <<"Sign/Verify API">>, since => <<"OTP 20.1">>}). -spec verify(Algorithm, DigestType, Msg, Signature, Key, Options) -> Result @@ -2604,17 +2584,17 @@ sign_verify_compatibility(Algorithm0, Type0, _Digest) -> %%% Only rsa works so far (although ecdsa | dss should do it) %%%================================================================ -doc "Algorithms for public key encrypt/decrypt. Only RSA is supported.". --doc(#{title => <<"Public Key Ciphers">>}). +-doc(#{group => <<"Public Key Ciphers">>}). -type pk_encrypt_decrypt_algs() :: rsa . --doc(#{title => <<"Public Key Ciphers">>,equiv => rsa_padding()}). +-doc(#{group => <<"Public Key Ciphers">>,equiv => rsa_padding()}). -type pk_encrypt_decrypt_opts() :: [rsa_opt()] | rsa_compat_opts(). -doc """ Those option forms are kept only for compatibility and should not be used in new code. """. --doc(#{title => <<"Public Key Ciphers">>}). +-doc(#{group => <<"Public Key Ciphers">>}). -type rsa_compat_opts() :: [{rsa_pad, rsa_padding()}] | rsa_padding() . @@ -2628,13 +2608,13 @@ Options for public key encrypt/decrypt. Only RSA is supported. > The exact set of options and there syntax _may_ be changed without prior > notice. """. --doc(#{title => <<"Public Key Ciphers">>}). +-doc(#{group => <<"Public Key Ciphers">>}). -type rsa_padding() :: rsa_pkcs1_padding | rsa_pkcs1_oaep_padding | rsa_x931_padding | rsa_no_padding. --doc(#{title => <<"Public Key Ciphers">>,equiv => rsa_padding()}). +-doc(#{group => <<"Public Key Ciphers">>,equiv => rsa_padding()}). -type rsa_opt() :: {rsa_padding, rsa_padding()} | {signature_md, atom()} | {rsa_mgf1_md, sha} @@ -2658,7 +2638,7 @@ Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. > This is a legacy function, for security reasons do not use together with rsa_pkcs1_padding. """. --doc(#{title => <<"Legacy RSA Encryption API">>, +-doc(#{group => <<"Legacy RSA Encryption API">>, since => <<"OTP R16B01">>}). -spec public_encrypt(Algorithm, PlainText, PublicKey, Options) -> CipherText when Algorithm :: pk_encrypt_decrypt_algs(), @@ -2688,7 +2668,7 @@ Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"Legacy RSA Encryption API">>, +-doc(#{group => <<"Legacy RSA Encryption API">>, since => <<"OTP R16B01">>}). -spec private_decrypt(Algorithm, CipherText, PrivateKey, Options) -> PlainText when Algorithm :: pk_encrypt_decrypt_algs(), @@ -2720,7 +2700,7 @@ Public-key decryption using the private key. See also `crypto:private_decrypt/4` > with [`verify/5`](`verify/5`) is the prefered solution. """. --doc(#{title => <<"Legacy RSA Encryption API">>, +-doc(#{group => <<"Legacy RSA Encryption API">>, since => <<"OTP R16B01">>}). -spec private_encrypt(Algorithm, PlainText, PrivateKey, Options) -> CipherText when Algorithm :: pk_encrypt_decrypt_algs(), @@ -2751,7 +2731,7 @@ Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. > with [`sign/4`](`sign/4`) is the prefered solution. """. --doc(#{title => <<"Legacy RSA Encryption API">>, +-doc(#{group => <<"Legacy RSA Encryption API">>, since => <<"OTP R16B01">>}). -spec public_decrypt(Algorithm, CipherText, PublicKey, Options) -> PlainText when Algorithm :: pk_encrypt_decrypt_algs(), @@ -2780,7 +2760,7 @@ pkey_crypt_nif(_Algorithm, _In, _Key, _Options, _IsPrivate, _IsEncrypt) -> ?nif_ %%%================================================================ -doc(#{equiv => generate_key/3}). --doc(#{title => <<"Key API">>, +-doc(#{group => <<"Key API">>, since => <<"OTP R16B01">>}). -spec generate_key(Type, Params) -> {PublicKey, PrivKeyOut} @@ -2812,7 +2792,7 @@ Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. > then the optional key length parameter must be at least 224, 256, 302, 352 and > 400 for group sizes of 2048, 3072, 4096, 6144 and 8192, respectively. """. --doc(#{title => <<"Key API">>, +-doc(#{group => <<"Key API">>, since => <<"OTP R16B01">>}). -spec generate_key(Type, Params, PrivKeyIn) -> {PublicKey, PrivKeyOut} @@ -2902,7 +2882,7 @@ See also `public_key:compute_key/2`. Uses the [3-tuple style](`m:crypto#error_3tup`) for error handling. """. --doc(#{title => <<"Key API">>, +-doc(#{group => <<"Key API">>, since => <<"OTP R16B01">>}). -spec compute_key(Type, OthersPublicKey, MyPrivateKey, Params) -> SharedSecret @@ -2978,7 +2958,7 @@ evp_compute_key_nif(_Curve, _OthersBin, _MyBin) -> ?nif_stub. %%% %%%================================================================ --doc(#{title => <<"Utility Functions">>}). +-doc(#{group => <<"Utility Functions">>}). -doc """ Perform bit-wise XOR (exclusive or) on the data supplied. @@ -2999,7 +2979,7 @@ exor(Bin1, Bin2) -> %%% %%%================================================================ --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP R16B01">>}). -doc "Compute the function `N^P mod M`.". -spec mod_pow(N, P, M) -> Result when N :: binary() | integer(), @@ -3023,13 +3003,13 @@ mod_pow(Base, Exponent, Prime) -> Identifies the key to be used. The format depends on the loaded engine. It is passed to the `ENGINE_load_(private|public)_key` functions in libcrypto. """. --doc(#{title => <<"Types for Engines">>}). +-doc(#{group => <<"Types for Engines">>}). -type key_id() :: string() | binary() . -doc "The password of the key stored in an engine.". --doc(#{title => <<"Types for Engines">>}). +-doc(#{group => <<"Types for Engines">>}). -type password() :: string() | binary() . --doc(#{title => <<"Types for Engines">>,equiv => engine_ref()}). +-doc(#{group => <<"Types for Engines">>,equiv => engine_ref()}). -type engine_key_ref() :: #{engine := engine_ref(), key_id := key_id(), password => password(), @@ -3038,13 +3018,13 @@ passed to the `ENGINE_load_(private|public)_key` functions in libcrypto. %%%---- Commands: -doc "Pre and Post commands for [engine_load/3 and /4](`engine_load/3`).". --doc(#{title => <<"Types for Engines">>}). +-doc(#{group => <<"Types for Engines">>}). -type engine_cmnd() :: {unicode:chardata(), unicode:chardata()}. %%---------------------------------------------------------------------- %% Function: engine_get_all_methods/0 %%---------------------------------------------------------------------- --doc(#{title => <<"Types for Engines">>}). +-doc(#{group => <<"Types for Engines">>}). -type engine_method_type() :: engine_method_rsa | engine_method_dsa | engine_method_dh | engine_method_rand | engine_method_ecdh | engine_method_ecdsa | engine_method_ciphers | engine_method_digests | engine_method_store | @@ -3052,7 +3032,7 @@ passed to the `ENGINE_load_(private|public)_key` functions in libcrypto. engine_method_ec. -doc "The result of a call to `engine_load/3`.". --doc(#{title => <<"Types for Engines">>}). +-doc(#{group => <<"Types for Engines">>}). -type engine_ref() :: term(). -doc """ @@ -3064,7 +3044,7 @@ underlying OpenSSL implementation. See also the chapter [Engine Load](engine_load.md#engine_load) in the User's Guide. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 20.2">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 20.2">>}). -spec engine_get_all_methods() -> Result when Result :: [engine_method_type()]. engine_get_all_methods() -> engine_get_all_methods_nif(). @@ -3086,7 +3066,7 @@ in the underlying OpenSSL implementation. See also the chapter [Engine Load](engine_load.md#engine_load) in the User's Guide. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 20.2">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 20.2">>}). -spec engine_load(EngineId, PreCmds, PostCmds) -> Result when EngineId::unicode:chardata(), PreCmds::[engine_cmnd()], @@ -3164,7 +3144,7 @@ the underlying OpenSSL implementation. See also the chapter [Engine Load](engine_load.md#engine_load) in the User's Guide. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 20.2">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 20.2">>}). -spec engine_unload(Engine) -> Result when Engine :: engine_ref(), Result :: ok | {error, Reason::term()}. engine_unload(Engine) -> @@ -3197,7 +3177,7 @@ the underlying OpenSSL implementation. See also the chapter [Engine Load](engine_load.md#engine_load) in the User's Guide. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 21.0.6">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 21.0.6">>}). -spec engine_by_id(EngineId) -> Result when EngineId :: unicode:chardata(), Result :: {ok, Engine::engine_ref()} | {error, Reason::term()} . engine_by_id(EngineId) -> @@ -3218,7 +3198,7 @@ The function raises a `error:badarg` if the parameters are in wrong format. It may also raise the exception `error:notsup` in case there is no engine support in the underlying OpenSSL implementation. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 21.0.6">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 21.0.6">>}). -spec engine_add(Engine) -> Result when Engine :: engine_ref(), Result :: ok | {error, Reason::term()} . engine_add(Engine) -> @@ -3234,7 +3214,7 @@ The function raises a `error:badarg` if the parameters are in wrong format. It may also raise the exception `error:notsup` in case there is no engine support in the underlying OpenSSL implementation. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 21.0.6">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 21.0.6">>}). -spec engine_remove(Engine) -> Result when Engine :: engine_ref(), Result :: ok | {error, Reason::term()} . engine_remove(Engine) -> @@ -3251,7 +3231,7 @@ The function raises a `error:badarg` if the parameters are in wrong format. It may also raise the exception `error:notsup` in case there is no engine support in the underlying OpenSSL implementation. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 25.1">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 25.1">>}). -spec engine_register(Engine, EngineMethods) -> Result when Engine :: engine_ref(), EngineMethods::[engine_method_type()], Result :: ok | {error, Reason::term()} . @@ -3274,7 +3254,7 @@ The function raises a `error:badarg` if the parameters are in wrong format. It may also raise the exception `error:notsup` in case there is no engine support in the underlying OpenSSL implementation. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 25.1">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 25.1">>}). -spec engine_unregister(Engine, EngineMethods) -> Result when Engine :: engine_ref(), EngineMethods::[engine_method_type()], Result :: ok | {error, Reason::term()} . @@ -3297,7 +3277,7 @@ The function raises a `error:badarg` if the parameters are in wrong format. It may also raise the exception `error:notsup` in case there is no engine support in the underlying OpenSSL implementation. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 21.0.6">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 21.0.6">>}). -spec engine_get_id(Engine) -> EngineId when Engine :: engine_ref(), EngineId :: unicode:chardata(). engine_get_id(Engine) -> @@ -3314,7 +3294,7 @@ The function raises a `error:badarg` if the parameters are in wrong format. It may also raise the exception `error:notsup` in case there is no engine support in the underlying OpenSSL implementation. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 21.0.6">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 21.0.6">>}). -spec engine_get_name(Engine) -> EngineName when Engine :: engine_ref(), EngineName :: unicode:chardata(). engine_get_name(Engine) -> @@ -3335,7 +3315,7 @@ Guide. May raise exception `error:notsup` in case engine functionality is not supported by the underlying OpenSSL implementation. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 20.2">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 20.2">>}). -spec engine_list() -> Result when Result :: [EngineId::unicode:chardata()]. engine_list() -> case engine_get_first_nif() of @@ -3376,7 +3356,7 @@ The function raises a `error:badarg` if the parameters are in wrong format. It may also raise the exception `error:notsup` in case there is no engine support in the underlying OpenSSL implementation. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 20.2">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 20.2">>}). -spec engine_ctrl_cmd_string(Engine, CmdName, CmdArg) -> Result when Engine::term(), CmdName::unicode:chardata(), @@ -3403,7 +3383,7 @@ The function raises a `error:badarg` if the parameters are in wrong format. It may also raise the exception `error:notsup` in case there is no engine support in the underlying OpenSSL implementation. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 20.2">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 20.2">>}). -spec engine_ctrl_cmd_string(Engine, CmdName, CmdArg, Optional) -> Result when Engine::term(), CmdName::unicode:chardata(), @@ -3450,7 +3430,7 @@ in the underlying OpenSSL implementation. See also the chapter [Engine Load](engine_load.md#engine_load) in the User's Guide. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 21.0.6">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 21.0.6">>}). -spec ensure_engine_loaded(EngineId, LibPath) -> Result when EngineId :: unicode:chardata(), LibPath :: unicode:chardata(), Result :: {ok, Engine::engine_ref()} | @@ -3718,7 +3698,7 @@ ec_generate_key_nif(_Curve, _Key) -> ?nif_stub. ecdh_compute_key_nif(_Others, _Curve, _My) -> ?nif_stub. --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 17.0">>}). -doc "Return all supported named elliptic curves.". -spec ec_curves() -> [EllipticCurve] when EllipticCurve :: ec_named_curve() @@ -3728,7 +3708,7 @@ ecdh_compute_key_nif(_Others, _Curve, _My) -> ?nif_stub. ec_curves() -> crypto_ec_curves:curves(). --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 17.0">>}). -doc "Return the defining parameters of a elliptic curve.". -spec ec_curve(CurveName) -> ExplicitCurve when CurveName :: ec_named_curve(), @@ -3742,7 +3722,7 @@ Fetch public key from a private key stored in an Engine. The key must be of the type indicated by the Type parameter. """. --doc(#{title => <<"Engine API">>,since => <<"OTP 20.2">>}). +-doc(#{group => <<"Engine API">>,since => <<"OTP 20.2">>}). -spec privkey_to_pubkey(Type, EnginePrivateKeyRef) -> PublicKey when Type :: rsa | dss, EnginePrivateKeyRef :: engine_key_ref(), PublicKey :: rsa_public() | dss_public() . @@ -3821,7 +3801,7 @@ Returns true if the binaries are identical, false if they are of the same length but not identical. The function raises an `error:badarg` exception if the binaries are of different size. """. --doc(#{title => <<"Utility Functions">>, since => <<"OTP 25.0">>}). +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 25.0">>}). -spec hash_equals(BinA, BinB) -> Result when BinA :: binary(), BinB :: binary(), @@ -3853,7 +3833,7 @@ int_to_bin_neg(X,Ds) -> int_to_bin_neg(X bsr 8, [(X band 255)|Ds]). -doc "Convert binary representation, of an integer, to an Erlang integer.". --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP R16B01">>}). -spec bytes_to_integer(binary()) -> integer() . bytes_to_integer(Bin) -> diff --git a/lib/ftp/src/ftp.erl b/lib/ftp/src/ftp.erl index dfa70cbe992e..312edb6babad 100644 --- a/lib/ftp/src/ftp.erl +++ b/lib/ftp/src/ftp.erl @@ -79,13 +79,6 @@ The possible error reasons and the corresponding diagnostic strings returned by - **`efnamena`** - Filename not allowed \[553]. """. --moduledoc(#{titles => - [{function,<<"Connection API">>}, - {function,<<"File Transfer API">>}, - {function,<<"Chunk File Transfer API">>}, - {function,<<"Info API">>}, - {function,<<"Update API">>} - ]}). -removed([{start_service, 1, "use ftp:open/2 instead"}, {stop_service, 1, "use ftp:close/1 instead"}]). @@ -137,7 +130,7 @@ stop() -> %% Description: Start an ftp client and connect to a host. %%-------------------------------------------------------------------------- --doc(#{title => <<"Connection API">>}). +-doc(#{group => <<"Connection API">>}). -doc(#{equiv => open/2}). -spec open(Host :: inet:hostname() | inet:ip_address()) -> {'ok', Client :: client()} | {'error', Reason :: term()}. @@ -150,7 +143,7 @@ open({option_list, Options}) when is_list(Options) -> open(Host) -> ftp_internal:open(Host). --doc(#{title => <<"Connection API">>}). +-doc(#{group => <<"Connection API">>}). -doc """ Starts a FTP client process and opens a session with the FTP server at `Host`. @@ -315,7 +308,7 @@ open(Host, Port) -> %%-------------------------------------------------------------------------- %% Description: Login with or without a supplied account name. %%-------------------------------------------------------------------------- --doc(#{title => <<"Connection API">>}). +-doc(#{group => <<"Connection API">>}). -doc """ Performs login of `User` with `Pass`. """. @@ -327,7 +320,7 @@ Performs login of `User` with `Pass`. user(Pid, User, Pass) -> ftp_internal:user(Pid, User, Pass). --doc(#{title => <<"Connection API">>}). +-doc(#{group => <<"Connection API">>}). -doc """ Performs login of `User` with `Pass` to the account specified by `Account`. """. @@ -344,7 +337,7 @@ user(Pid, User, Pass, Account) -> %% Description: Set a user Account. %%-------------------------------------------------------------------------- --doc(#{title => <<"Connection API">>}). +-doc(#{group => <<"Connection API">>}). -doc """ Sets the account for an operation, if needed. """. @@ -357,7 +350,7 @@ account(Pid, Acc) -> %%-------------------------------------------------------------------------- %% Description: Get the current working directory at remote server. %%-------------------------------------------------------------------------- --doc(#{title => <<"Info API">>}). +-doc(#{group => <<"Info API">>}). -doc """ Returns the current working directory at the remote server. """. @@ -371,7 +364,7 @@ pwd(Pid) -> %%-------------------------------------------------------------------------- %% Description: Get the current working directory at local server. %%-------------------------------------------------------------------------- --doc(#{title => <<"Info API">>}). +-doc(#{group => <<"Info API">>}). -doc """ Returns the current working directory at the local client. """. @@ -385,7 +378,7 @@ lpwd(Pid) -> %%-------------------------------------------------------------------------- %% Description: Change current working directory at remote server. %%-------------------------------------------------------------------------- --doc(#{title => <<"Update API">>}). +-doc(#{group => <<"Update API">>}). -doc """ Changes the working directory at the remote server to `Dir`. """. @@ -398,7 +391,7 @@ cd(Pid, Dir) -> %%-------------------------------------------------------------------------- %% Description: Change current working directory for the local client. %%-------------------------------------------------------------------------- --doc(#{title => <<"Update API">>}). +-doc(#{group => <<"Update API">>}). -doc """ Changes the working directory to `Dir` for the local client. """. @@ -411,7 +404,7 @@ lcd(Pid, Dir) -> %%-------------------------------------------------------------------------- %% Description: Returns a list of files in long format. %%-------------------------------------------------------------------------- --doc(#{title => <<"Info API">>}). +-doc(#{group => <<"Info API">>}). -doc(#{equiv => ls/2}). -spec ls(Client ::client()) -> {'ok', Listing :: string()} | @@ -420,7 +413,7 @@ lcd(Pid, Dir) -> ls(Pid) -> ls(Pid, ""). --doc(#{title => <<"Info API">>}). +-doc(#{group => <<"Info API">>}). -doc """ Returns a list of files in long format. @@ -443,7 +436,7 @@ ls(Pid, Dir) -> %% Description: Returns a list of files in short format %%-------------------------------------------------------------------------- --doc(#{title => <<"Info API">>}). +-doc(#{group => <<"Info API">>}). -doc(#{equiv => nlist/2}). -spec nlist(Client ::client()) -> {'ok', Listing :: string()} | @@ -452,7 +445,7 @@ ls(Pid, Dir) -> nlist(Pid) -> nlist(Pid, ""). --doc(#{title => <<"Info API">>}). +-doc(#{group => <<"Info API">>}). -doc """ Returns a list of files in short format. @@ -475,7 +468,7 @@ nlist(Pid, Dir) -> %%-------------------------------------------------------------------------- %% Description: Rename a file at remote server. %%-------------------------------------------------------------------------- --doc(#{title => <<"Update API">>}). +-doc(#{group => <<"Update API">>}). -doc """ Renames `Old` to `New` at the remote server. """. @@ -489,7 +482,7 @@ rename(Pid, Old, New) -> %% Description: Remove file at remote server. %%-------------------------------------------------------------------------- --doc(#{title => <<"Update API">>}). +-doc(#{group => <<"Update API">>}). -doc """ Deletes the file `File` at the remote server. """. @@ -502,7 +495,7 @@ delete(Pid, File) -> %%-------------------------------------------------------------------------- %% Description: Make directory at remote server. %%-------------------------------------------------------------------------- --doc(#{title => <<"Update API">>}). +-doc(#{group => <<"Update API">>}). -doc """ Creates the directory `Dir` at the remote server. """. @@ -515,7 +508,7 @@ mkdir(Pid, Dir) -> %%-------------------------------------------------------------------------- %% Description: Remove directory at remote server. %%-------------------------------------------------------------------------- --doc(#{title => <<"Update API">>}). +-doc(#{group => <<"Update API">>}). -doc """ Removes directory `Dir` at the remote server. """. @@ -528,7 +521,7 @@ rmdir(Pid, Dir) -> %%-------------------------------------------------------------------------- %% Description: Set transfer type. %%-------------------------------------------------------------------------- --doc(#{title => <<"Update API">>}). +-doc(#{group => <<"Update API">>}). -doc """ Sets the file transfer type to `ascii` or `binary`. When an FTP session is opened, the default transfer type of the server is used, most often `ascii`, @@ -545,7 +538,7 @@ type(Pid, Type) -> %% Description: Transfer file from remote server. %%-------------------------------------------------------------------------- --doc(#{title => <<"File Transfer API">>}). +-doc(#{group => <<"File Transfer API">>}). -doc(#{equiv => recv/3}). -spec recv(Client ::client(), RemoteFileName :: file:filename()) -> 'ok' | {'error', Reason :: term()}. @@ -553,7 +546,7 @@ type(Pid, Type) -> recv(Pid, RemoteFileName) -> ftp_internal:recv(Pid, RemoteFileName). --doc(#{title => <<"File Transfer API">>}). +-doc(#{group => <<"File Transfer API">>}). -doc """ Transfers the file `RemoteFileName` from the remote server to the file system of the local client. If `LocalFileName` is specified, the local file will be @@ -575,7 +568,7 @@ recv(Pid, RemoteFileName, LocalFileName) -> %% Description: Transfer file from remote server into binary. %%-------------------------------------------------------------------------- --doc(#{title => <<"File Transfer API">>}). +-doc(#{group => <<"File Transfer API">>}). -doc """ Transfers the file `RemoteFile` from the remote server and receives it as a binary. @@ -591,7 +584,7 @@ recv_bin(Pid, RemoteFile) -> %%-------------------------------------------------------------------------- %% Description: Start receive of chunks of remote file. %%-------------------------------------------------------------------------- --doc(#{title => <<"Chunk File Transfer API">>}). +-doc(#{group => <<"Chunk File Transfer API">>}). -doc """ Starts transfer of the file `RemoteFile` from the remote server. """. @@ -606,7 +599,7 @@ recv_chunk_start(Pid, RemoteFile) -> %%-------------------------------------------------------------------------- %% Description: Transfer file from remote server into binary in chunks %%-------------------------------------------------------------------------- --doc(#{title => <<"Chunk File Transfer API">>}). +-doc(#{group => <<"Chunk File Transfer API">>}). -doc """ Receives a chunk of the remote file (`RemoteFile` of `recv_chunk_start`). The return values have the following meaning: @@ -628,7 +621,7 @@ recv_chunk(Pid) -> %% Description: Transfer file to remote server. %%-------------------------------------------------------------------------- --doc(#{title => <<"File Transfer API">>}). +-doc(#{group => <<"File Transfer API">>}). -doc(#{equiv => send/3}). -spec send(Client ::client(), LocalFileName :: file:filename()) -> 'ok' | {'error', Reason :: term()}. @@ -636,7 +629,7 @@ recv_chunk(Pid) -> send(Pid, LocalFileName) -> send(Pid, LocalFileName, LocalFileName). --doc(#{title => <<"File Transfer API">>}). +-doc(#{group => <<"File Transfer API">>}). -doc """ Transfers the file `LocalFileName` to the remote server. If `RemoteFileName` is specified, the name of the remote file is set to `RemoteFileName`, otherwise to @@ -654,7 +647,7 @@ send(Pid, LocalFileName, RemotFileName) -> %%-------------------------------------------------------------------------- %% Description: Transfer a binary to a remote file. %%-------------------------------------------------------------------------- --doc(#{title => <<"File Transfer API">>}). +-doc(#{group => <<"File Transfer API">>}). -doc """ Transfers the binary `Bin` into the file `RemoteFile` at the remote server. """. @@ -668,7 +661,7 @@ send_bin(Pid, Bin, RemoteFile) -> %%-------------------------------------------------------------------------- %% Description: Start transfer of chunks to remote file. %%-------------------------------------------------------------------------- --doc(#{title => <<"Chunk File Transfer API">>}). +-doc(#{group => <<"Chunk File Transfer API">>}). -doc """ Starts transfer of chunks into the file `RemoteFile` at the remote server. """. @@ -681,7 +674,7 @@ send_chunk_start(Pid, RemoteFile) -> %%-------------------------------------------------------------------------- %% Description: Start append chunks of data to remote file. %%-------------------------------------------------------------------------- --doc(#{title => <<"Chunk File Transfer API">>}). +-doc(#{group => <<"Chunk File Transfer API">>}). -doc """ Starts the transfer of chunks for appending to the file `RemoteFile` at the remote server. If the file does not exist, it is created. @@ -696,7 +689,7 @@ append_chunk_start(Pid, RemoteFile) -> %%-------------------------------------------------------------------------- %% Purpose: Send chunk to remote file. %%-------------------------------------------------------------------------- --doc(#{title => <<"Chunk File Transfer API">>}). +-doc(#{group => <<"Chunk File Transfer API">>}). -doc """ Transfers the chunk `Bin` to the remote server, which writes it into the file specified in the call to [`send_chunk_start/2`](`send_chunk_start/2`). @@ -713,7 +706,7 @@ send_chunk(Pid, Bin) -> %%-------------------------------------------------------------------------- %% Description: Append chunk to remote file. %%-------------------------------------------------------------------------- --doc(#{title => <<"Chunk File Transfer API">>}). +-doc(#{group => <<"Chunk File Transfer API">>}). -doc """ Transfers the chunk `Bin` to the remote server, which appends it to the file specified in the call to [`append_chunk_start/2`](`append_chunk_start/2`). @@ -732,7 +725,7 @@ append_chunk(Pid, Bin) -> %% Description: End sending of chunks to remote file. %%-------------------------------------------------------------------------- --doc(#{title => <<"Chunk File Transfer API">>}). +-doc(#{group => <<"Chunk File Transfer API">>}). -doc """ Stops transfer of chunks to the remote server. The file at the remote server, specified in the call to [`send_chunk_start/2`](`send_chunk_start/2`) is closed @@ -749,7 +742,7 @@ send_chunk_end(Pid) -> %% Description: End appending of chunks to remote file. %%-------------------------------------------------------------------------- --doc(#{title => <<"Chunk File Transfer API">>}). +-doc(#{group => <<"Chunk File Transfer API">>}). -doc """ Stops transfer of chunks for appending to the remote server. The file at the remote server, specified in the call to @@ -766,7 +759,7 @@ append_chunk_end(Pid) -> %% Description: Append the local file to the remote file %%-------------------------------------------------------------------------- --doc(#{title => <<"Update API">>}). +-doc(#{group => <<"Update API">>}). -doc(#{equiv => append/3}). -spec append(Client ::client(), LocalFileName :: file:filename()) -> 'ok' | {'error', Reason :: term()}. @@ -774,7 +767,7 @@ append_chunk_end(Pid) -> append(Pid, LocalFileName) -> append(Pid, LocalFileName, LocalFileName). --doc(#{title => <<"Update API">>}). +-doc(#{group => <<"Update API">>}). -doc """ Transfers the file `LocalFile` to the remote server. If `RemoteFile` is specified, the name of the remote file that the file is appended to is set to @@ -794,7 +787,7 @@ append(Pid, LocalFileName, RemotFileName) -> %% Purpose: Append a binary to a remote file. %%-------------------------------------------------------------------------- --doc(#{title => <<"Update API">>}). +-doc(#{group => <<"Update API">>}). -doc """ Transfers the binary `Bin` to the remote server and appends it to the file `RemoteFile`. If the file does not exist, it is created. @@ -838,7 +831,7 @@ quote(Pid, Cmd) when is_list(Cmd) -> %% Description: End the ftp session. %%-------------------------------------------------------------------------- --doc(#{title => <<"Connection API">>}). +-doc(#{group => <<"Connection API">>}). -doc """ Ends an FTP session, created using function [open](`open/2`). """. @@ -851,7 +844,7 @@ close(Pid) -> %% Description: Return diagnostics. %%-------------------------------------------------------------------------- --doc(#{title => <<"Info API">>}). +-doc(#{group => <<"Info API">>}). -doc """ Given an error return value `{error, AtomReason}`, this function returns a readable string describing the error. diff --git a/lib/inets/src/http_server/httpd.erl b/lib/inets/src/http_server/httpd.erl index b467329afedf..4b81dbd4e07d 100644 --- a/lib/inets/src/http_server/httpd.erl +++ b/lib/inets/src/http_server/httpd.erl @@ -796,9 +796,6 @@ The fields of record `mod` have the following meaning: [RFC 2616](http://www.ietf.org/rfc/rfc2616.txt), `m:inets`, `m:ssl` """. --moduledoc(#{titles => - [{callback,<<"Web server API callback functions">>}, - {function,<<"Web server API help functions">>}]}). -behaviour(inets_service). @@ -866,7 +863,7 @@ atom `sent` if the HTTP response is sent back to the client. If `close` is returned from the fun, something has gone wrong and the server signals this to the client by closing the connection. """. --doc(#{title => <<"ERLANG WEB SERVER API CALLBACK FUNCTIONS">>}). +-doc(#{group => <<"ERLANG WEB SERVER API CALLBACK FUNCTIONS">>}). -callback do(ModData) -> {proceed, OldData} | {proceed, NewData} | {break, NewData} | done when ModData :: [{data,NewData} | {'Body', Body} | {'Head',Head}], OldData :: list(), @@ -885,7 +882,7 @@ When `httpd` is shut down, it tries to execute [`remove/1`](`c:remove/1`) in each Erlang web server callback module. The programmer can use this function to clean up resources created in the store function. """. --doc(#{title => <<"ERLANG WEB SERVER API CALLBACK FUNCTIONS">>}). +-doc(#{group => <<"ERLANG WEB SERVER API CALLBACK FUNCTIONS">>}). -callback remove(ConfigDB) -> ok | {error, Reason} when ConfigDB :: ets:tid(), Reason :: term(). @@ -897,7 +894,7 @@ resolve possible dependencies among configuration options by changing the value of the option. This function only needs clauses for the options implemented by this particular callback module. """. --doc(#{title => <<"ERLANG WEB SERVER API CALLBACK FUNCTIONS">>}). +-doc(#{group => <<"ERLANG WEB SERVER API CALLBACK FUNCTIONS">>}). -callback store({Option, Value}, Config) -> {ok, {Option, NewValue}} | {error, Reason} when Option :: property(), @@ -917,7 +914,7 @@ this particular callback module. scripts (see `m:mod_esi`) as defined in the standard URL format, that is, '+' becomes 'space' and decoding of hexadecimal characters (`%xx`). """. --doc(#{title => <<"Web server API help functions">>}). +-doc(#{group => <<"Web server API help functions">>}). -spec parse_query(QueryString) -> QueryList | uri_string:error() when QueryString :: string(), QueryList :: [{unicode:chardata(), unicode:chardata() | true}]. diff --git a/lib/inets/src/http_server/mod_esi.erl b/lib/inets/src/http_server/mod_esi.erl index 76f9420bbc71..382c1533358a 100644 --- a/lib/inets/src/http_server/mod_esi.erl +++ b/lib/inets/src/http_server/mod_esi.erl @@ -61,7 +61,6 @@ The following data types are used in the functions for mod_esi: - **`{http_LowerCaseHTTPHeaderName, string()}`** - example: \{http_content_type, "text/html"\} """. --moduledoc(#{titles => [{callback,<<"ESI Callback Functions">>}]}). %% API %% Functions provided to help erl scheme alias programmer to @@ -143,7 +142,7 @@ where `Input` is `{first, Data::binary()}` or The input `State` is the last returned `State`, in it the callback can include any data that it needs to keep track of when handling the chunks. """. --doc(#{title => <<"ESI Callback Functions">>}). +-doc(#{group => <<"ESI Callback Functions">>}). -callback 'Function'(SessionID, Env, Input) -> {continue, State} | _ when SessionID :: term(), diff --git a/lib/kernel/src/application.erl b/lib/kernel/src/application.erl index 350312c09d1b..6120870b5dd9 100644 --- a/lib/kernel/src/application.erl +++ b/lib/kernel/src/application.erl @@ -47,7 +47,6 @@ For details about applications and behaviours, see [OTP Design Principles](`e:system:design_principles.md`), [kernel](kernel_app.md), [app](app.md) """. --moduledoc(#{titles => [{callback,<<"Callback Module">>}]}). -export([ensure_all_started/1, ensure_all_started/2, ensure_all_started/3, start/1, start/2, start_boot/1, start_boot/2, stop/1, @@ -128,7 +127,7 @@ of the top supervisor and `State` is any term. If omitted, `State` defaults to `[]`. If the application is stopped later, `State` is passed to [`Module:prep_stop/1`](`c:prep_stop/1`). """. --doc(#{title => <<"Callback Module">>}). +-doc(#{group => <<"Callback Module">>}). -callback start(StartType :: start_type(), StartArgs :: term()) -> {'ok', pid()} | {'ok', pid(), State :: term()} | {'error', Reason :: term()}. @@ -141,7 +140,7 @@ cleaning up. The return value is ignored. a function exists. Otherwise `State` is taken from the return value of [`Module:start/2`](`c:start/2`). """. --doc(#{title => <<"Callback Module">>}). +-doc(#{group => <<"Callback Module">>}). -callback stop(State :: term()) -> term(). @@ -157,7 +156,7 @@ parameters. `Removed` is a list of all removed parameters. """. --doc(#{title => <<"Callback Module">>}). +-doc(#{group => <<"Callback Module">>}). -callback config_change(Changed, New, Removed) -> ok when Changed :: [{Par, Val}], New :: [{Par, Val}], @@ -176,7 +175,7 @@ no state was returned. `NewState` is any term and is passed to The function is optional. If it is not defined, the processes are terminated and then [`Module:stop(State)`](`c:stop/1`) is called. """. --doc(#{title => <<"Callback Module">>}). +-doc(#{group => <<"Callback Module">>}). -callback prep_stop(State) -> NewState when State :: term(), NewState :: term(). @@ -195,7 +194,7 @@ which the start phase is defined. For a description of `StartType`, see [`Module:start/2`](`c:start/2`). """. --doc(#{title => <<"Callback Module">>}). +-doc(#{group => <<"Callback Module">>}). -callback start_phase(Phase, StartType, PhaseArgs) -> ok | {error, Reason} when Phase :: atom(), diff --git a/lib/kernel/src/gen_sctp.erl b/lib/kernel/src/gen_sctp.erl index c32562d52d0b..71d55f93bd09 100644 --- a/lib/kernel/src/gen_sctp.erl +++ b/lib/kernel/src/gen_sctp.erl @@ -20,9 +20,6 @@ -module(gen_sctp). --moduledoc(#{titles => - [{type,<<"Exported data types">>}, - {type,<<"Internal data types">>}]}). -moduledoc """ Interface to SCTP sockets. @@ -661,17 +658,17 @@ identifies an association for an SCTP socket. The term is opaque except for the special value `0`, which has a meaning such as "the whole endpoint" or "all future associations". """. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type assoc_id() :: term(). -doc "[SCTP Socket Option](#options) name and value, to set.". --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type option() :: elementary_option() | record_option(). -doc "[SCTP Socket Option](#options) name, to get.". --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type option_name() :: elementary_option_name() | record_option() | @@ -680,13 +677,13 @@ future associations". -doc """ [SCTP Socket Option](#options) name and value, what you get. """. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type option_value() :: elementary_option() | record_option() | ro_option(). --doc(#{title => <<"Internal data types">>}). +-doc(#{group => <<"Internal data types">>}). -type elementary_option() :: {active, true | false | once | -32768..32767} | {buffer, non_neg_integer()} | @@ -717,7 +714,7 @@ future associations". {recvtclass, boolean()} | {recvttl, boolean()}. --doc(#{title => <<"Internal data types">>}). +-doc(#{group => <<"Internal data types">>}). -type elementary_option_name() :: active | buffer | @@ -748,7 +745,7 @@ future associations". recvtclass | recvttl. --doc(#{title => <<"Internal data types">>}). +-doc(#{group => <<"Internal data types">>}). -type record_option() :: {sctp_adaptation_layer, #sctp_setadaptation{}} | {sctp_associnfo, #sctp_assocparams{}} | @@ -761,13 +758,13 @@ future associations". {sctp_rtoinfo, #sctp_rtoinfo{}} | {sctp_set_peer_primary_addr, #sctp_setpeerprim{}}. --doc(#{title => <<"Internal data types">>}). +-doc(#{group => <<"Internal data types">>}). -type ro_option() :: {sctp_get_peer_addr_info, #sctp_paddrinfo{}} | {sctp_status, #sctp_status{}}. -doc "Socket identifier returned from [`open/*`](`open/0`).". --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type sctp_socket() :: port(). -export_type( diff --git a/lib/kernel/src/inet.erl b/lib/kernel/src/inet.erl index f6c5989728dd..e4ec7bec5c2c 100644 --- a/lib/kernel/src/inet.erl +++ b/lib/kernel/src/inet.erl @@ -237,9 +237,6 @@ Function `parse_address/1` can be useful: - `exfull` - Message tables full - `nxdomain` - Hostname or domain name cannot be found """. --moduledoc(#{titles => - [{type,<<"Exported data types">>}, - {type,<<"Internal data types">>}]}). -include("inet.hrl"). -include("inet_int.hrl"). @@ -355,23 +352,23 @@ Add the following directive to the module: -include_lib("kernel/include/inet.hrl"). ``` """. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type hostent() :: #hostent{}. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type hostname() :: atom() | string(). --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type ip4_address() :: {0..255,0..255,0..255,0..255}. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type ip6_address() :: {0..65535,0..65535,0..65535,0..65535, 0..65535,0..65535,0..65535,0..65535}. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type ip_address() :: ip4_address() | ip6_address(). --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type port_number() :: 0..65535. -doc """ @@ -382,7 +379,7 @@ where `Family` is an atom such as `local` and the format of `Destination` depends on `Family`. `Destination` is a complete address (for example an IP address with port number). """. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type family_address() :: inet_address() | inet6_address() | local_address(). -doc """ @@ -392,7 +389,7 @@ A network address for the `inet` family (`AF_INET`, IPv4) > This address format is currently experimental and for completeness > to make all address families have a `{Family, Destination}` representation. """. --doc(#{title => <<"Internal data types">>}). +-doc(#{group => <<"Internal data types">>}). -type inet_address() :: {'inet', {ip4_address() | 'any' | 'loopback', port_number()}}. @@ -403,7 +400,7 @@ A network address for the `inet6` family (`AF_INET6`, IPv6) > This address format is currently experimental and for completeness > to make all address families have a `{Family, Destination}` representation. """. --doc(#{title => <<"Internal data types">>}). +-doc(#{group => <<"Internal data types">>}). -type inet6_address() :: {'inet6', {ip6_address() | 'any' | 'loopback', port_number()}}. @@ -427,7 +424,7 @@ on your system, normally `unix` in manual section 7. In most API functions where you can use this address family the port number must be `0`. """. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type local_address() :: {'local', File :: binary() | string()}. -doc """ @@ -440,7 +437,7 @@ if the other side has no socket address. The `undefined` family can only occur in the unlikely event of an address family that the VM doesn't recognize. """. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type returned_non_ip_address() :: {'local', binary()} | {'unspec', <<>>} | @@ -453,7 +450,7 @@ An atom that is named from the POSIX error codes used in Unix, and in the runtime libraries of most C compilers. See section [POSIX Error Codes](#posix-error-codes). """. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type posix() :: 'eaddrinuse' | 'eaddrnotavail' | 'eafnosupport' | 'ealready' | 'econnaborted' | 'econnrefused' | 'econnreset' | @@ -477,7 +474,7 @@ A socket recognized by this module and its siblings. See `t:gen_tcp:socket/0` and `t:gen_udp:socket/0`. """. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type socket() :: port() | module_socket(). -doc """ @@ -490,19 +487,19 @@ the `m:socket` module and its NIF implementation. This is a _temporary_ option that will be ignored in a future release. """. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type inet_backend() :: {'inet_backend', 'inet' | 'socket'}. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type socket_setopt() :: gen_sctp:option() | gen_tcp:option() | gen_udp:option(). --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type socket_optval() :: gen_sctp:option_value() | gen_tcp:option() | gen_udp:option() | gen_tcp:pktoptions_value(). --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type socket_getopt() :: gen_sctp:option_name() | gen_tcp:option_name() | gen_udp:option_name(). @@ -575,7 +572,7 @@ by the Solaris API function `getaddrinfo()`. > `Netmask` and `Broadaddr` values may be calculated, just as some `Flags` > values. """. --doc(#{title => <<"Internal data types">>}). +-doc(#{group => <<"Internal data types">>}). -type getifaddrs_ifopts() :: [Ifopt :: {flags, Flags :: [up | broadcast | loopback | pointtopoint | running | multicast]} | @@ -585,19 +582,19 @@ by the Solaris API function `getaddrinfo()`. {dstaddr, Dstaddr :: ip_address()} | {hwaddr, Hwaddr :: [byte()]}]. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type address_family() :: 'inet' | 'inet6' | 'local'. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type socket_protocol() :: 'tcp' | 'udp' | 'sctp'. -type socket_type() :: 'stream' | 'dgram' | 'seqpacket'. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type socket_address() :: ip_address() | 'any' | 'loopback' | local_address(). --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type stat_option() :: 'recv_cnt' | 'recv_max' | 'recv_avg' | 'recv_oct' | 'recv_dvi' | 'send_cnt' | 'send_max' | 'send_avg' | 'send_oct' | 'send_pend'. @@ -616,7 +613,7 @@ The value(s) correspond to the currently active socket or for a single send operation the option(s) to override the currently active socket option(s). """. --doc(#{title => <<"Exported data types">>}). +-doc(#{group => <<"Exported data types">>}). -type ancillary_data() :: [ {'tos', byte()} | {'tclass', byte()} | {'ttl', byte()} ]. diff --git a/lib/kernel/src/inet_res.erl b/lib/kernel/src/inet_res.erl index 0c47b1fb3c72..ca24005858c9 100644 --- a/lib/kernel/src/inet_res.erl +++ b/lib/kernel/src/inet_res.erl @@ -21,7 +21,6 @@ %% -module(inet_res). --moduledoc(#{titles => [{function,<<"Legacy Functions">>}]}). -moduledoc """ A rudimentary DNS client. @@ -415,7 +414,7 @@ lookup_filter({error,_}, _, _) -> []. %% To be deprecated -doc(#{equiv => nslookup(Name, Class, Type, infinity)}). --doc(#{title => <<"Legacy Functions">>}). +-doc(#{group => <<"Legacy Functions">>}). -spec nslookup(Name, Class, Type) -> {ok, dns_msg()} | {error, Reason} when Name :: dns_name() | inet:ip_address(), Class :: dns_class(), @@ -437,7 +436,7 @@ With argument `Timeout` calls `resolve/5` with `Opts = []`. With argument `Nameservers` calls `resolve/5` with `Opts = [{nameservers, Nameservers}]` and `Timeout = infinity`. """. --doc(#{title => <<"Legacy Functions">>}). +-doc(#{group => <<"Legacy Functions">>}). -spec nslookup(Name, Class, Type, Timeout) -> {ok, dns_msg()} | {error, Reason} when Name :: dns_name() | inet:ip_address(), @@ -461,7 +460,7 @@ nslookup(Name, Class, Type, NSs) -> % For backwards compatibility nnslookup(Name, Class, Type, NSs). % with OTP R6B only -doc(#{equiv => nnslookup(Name, Class, Type, NSs, infinity)}). --doc(#{title => <<"Legacy Functions">>}). +-doc(#{group => <<"Legacy Functions">>}). -spec nnslookup(Name, Class, Type, Nameservers) -> {ok, dns_msg()} | {error, Reason} when Name :: dns_name() | inet:ip_address(), @@ -479,7 +478,7 @@ Resolve a DNS query. Like `nslookup/4` but calls `resolve/5` with both the arguments `Opts = [{nameservers, Nameservers}]` and `Timeout`. """. --doc(#{title => <<"Legacy Functions">>}). +-doc(#{group => <<"Legacy Functions">>}). -spec nnslookup(Name, Class, Type, Nameservers, Timeout) -> {ok, dns_msg()} | {error, Reason} when Name :: dns_name() | inet:ip_address(), diff --git a/lib/kernel/src/logger.erl b/lib/kernel/src/logger.erl index fb1409c1658c..002c7bfe8e96 100644 --- a/lib/kernel/src/logger.erl +++ b/lib/kernel/src/logger.erl @@ -100,11 +100,7 @@ equal to or below the configured log level. `m:logger_filters`, `m:logger_handler`, `m:logger_formatter`, `m:logger_std_h`, `m:unicode` """. --moduledoc(#{since => "OTP 21.0", - titles => - [{function,<<"Logging API functions">>}, - {function,<<"Configuration API functions">>}, - {function,<<"Miscellaneous API functions">>}]}). +-moduledoc(#{since => "OTP 21.0"}). %% Log interface -export([emergency/1,emergency/2,emergency/3, @@ -352,14 +348,14 @@ Equivalent to [`" Level "(FormatOrFun, Args, #{})`](`" Level "/3`) if called as -define(LOG_DOC_3(Level), #{equiv => log(Level, FormatOrFun, Args, Metadata) } ). -doc ?LOG_DOC_1(emergency). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec emergency(String :: unicode:chardata()) -> ok; (Report :: report()) -> ok. emergency(StringOrReport) -> log(emergency,StringOrReport). -doc ?LOG_DOC_2("emergency"). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec emergency(String :: unicode:chardata(), Metadata :: metadata()) -> ok; (Report :: report(), Metadata :: metadata()) -> ok; (Format :: io:format(), Args :: [term()]) -> ok; @@ -368,20 +364,20 @@ emergency(FormatOrFun,Args) -> log(emergency,FormatOrFun,Args). -doc ?LOG_DOC_3(emergency). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec emergency(Format :: io:format(), Args :: [term()], Metadata :: metadata()) -> ok; (Fun :: msg_fun(), FunArgs :: term(), Metadata :: metadata()) -> ok. emergency(FormatOrFun,Args,Metadata) -> log(emergency,FormatOrFun,Args,Metadata). -doc ?LOG_DOC_1(alert). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec alert(String :: unicode:chardata()) -> ok; (Report :: report()) -> ok. alert(StringOrReport) -> log(alert,StringOrReport). -doc ?LOG_DOC_2("alert"). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec alert(String :: unicode:chardata(), Metadata :: metadata()) -> ok; (Report :: report(), Metadata :: metadata()) -> ok; (Format :: io:format(), Args :: [term()]) -> ok; @@ -389,20 +385,20 @@ alert(StringOrReport) -> alert(FormatOrFun,Args) -> log(alert,FormatOrFun,Args). -doc ?LOG_DOC_3(alert). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec alert(Format :: io:format(), Args :: [term()], Metadata :: metadata()) -> ok; (Fun :: msg_fun(), FunArgs :: term(), Metadata :: metadata()) -> ok. alert(FormatOrFun,Args,Metadata) -> log(alert,FormatOrFun,Args,Metadata). -doc ?LOG_DOC_1(critical). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec critical(String :: unicode:chardata()) -> ok; (Report :: report()) -> ok. critical(StringOrReport) -> log(critical,StringOrReport). -doc ?LOG_DOC_2("critical"). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec critical(String :: unicode:chardata(), Metadata :: metadata()) -> ok; (Report :: report(), Metadata :: metadata()) -> ok; (Format :: io:format(), Args :: [term()]) -> ok; @@ -410,20 +406,20 @@ critical(StringOrReport) -> critical(FormatOrFun,Args) -> log(critical,FormatOrFun,Args). -doc ?LOG_DOC_3(critical). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec critical(Format :: io:format(), Args :: [term()], Metadata :: metadata()) -> ok; (Fun :: msg_fun(), FunArgs :: term(), Metadata :: metadata()) -> ok. critical(FormatOrFun,Args,Metadata) -> log(critical,FormatOrFun,Args,Metadata). -doc ?LOG_DOC_1(error). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec error(String :: unicode:chardata()) -> ok; (Report :: report()) -> ok. error(StringOrReport) -> log(error,StringOrReport). -doc ?LOG_DOC_2("error"). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec error(String :: unicode:chardata(), Metadata :: metadata()) -> ok; (Report :: report(), Metadata :: metadata()) -> ok; (Format :: io:format(), Args :: [term()]) -> ok; @@ -431,20 +427,20 @@ error(StringOrReport) -> error(FormatOrFun,Args) -> log(error,FormatOrFun,Args). -doc ?LOG_DOC_3(error). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec error(Format :: io:format(), Args :: [term()], Metadata :: metadata()) -> ok; (Fun :: msg_fun(), FunArgs :: term(), Metadata :: metadata()) -> ok. error(FormatOrFun,Args,Metadata) -> log(error,FormatOrFun,Args,Metadata). -doc ?LOG_DOC_1(warning). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec warning(String :: unicode:chardata()) -> ok; (Report :: report()) -> ok. warning(StringOrReport) -> log(warning,StringOrReport). -doc ?LOG_DOC_2("warning"). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec warning(String :: unicode:chardata(), Metadata :: metadata()) -> ok; (Report :: report(), Metadata :: metadata()) -> ok; (Format :: io:format(), Args :: [term()]) -> ok; @@ -452,20 +448,20 @@ warning(StringOrReport) -> warning(FormatOrFun,Args) -> log(warning,FormatOrFun,Args). -doc ?LOG_DOC_3(warning). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec warning(Format :: io:format(), Args :: [term()], Metadata :: metadata()) -> ok; (Fun :: msg_fun(), FunArgs :: term(), Metadata :: metadata()) -> ok. warning(FormatOrFun,Args,Metadata) -> log(warning,FormatOrFun,Args,Metadata). -doc ?LOG_DOC_1(notice). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec notice(String :: unicode:chardata()) -> ok; (Report :: report()) -> ok. notice(StringOrReport) -> log(notice,StringOrReport). -doc ?LOG_DOC_2("notice"). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec notice(String :: unicode:chardata(), Metadata :: metadata()) -> ok; (Report :: report(), Metadata :: metadata()) -> ok; (Format :: io:format(), Args :: [term()]) -> ok; @@ -473,20 +469,20 @@ notice(StringOrReport) -> notice(FormatOrFun,Args) -> log(notice,FormatOrFun,Args). -doc ?LOG_DOC_3(notice). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec notice(Format :: io:format(), Args :: [term()], Metadata :: metadata()) -> ok; (Fun :: msg_fun(), FunArgs :: term(), Metadata :: metadata()) -> ok. notice(FormatOrFun,Args,Metadata) -> log(notice,FormatOrFun,Args,Metadata). -doc ?LOG_DOC_1(info). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec info(String :: unicode:chardata()) -> ok; (Report :: report()) -> ok. info(StringOrReport) -> log(info,StringOrReport). -doc ?LOG_DOC_2("info"). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec info(String :: unicode:chardata(), Metadata :: metadata()) -> ok; (Report :: report(), Metadata :: metadata()) -> ok; (Format :: io:format(), Args :: [term()]) -> ok; @@ -494,20 +490,20 @@ info(StringOrReport) -> info(FormatOrFun,Args) -> log(info,FormatOrFun,Args). -doc ?LOG_DOC_3(info). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec info(Format :: io:format(), Args :: [term()], Metadata :: metadata()) -> ok; (Fun :: msg_fun(), FunArgs :: term(), Metadata :: metadata()) -> ok. info(FormatOrFun,Args,Metadata) -> log(info,FormatOrFun,Args,Metadata). -doc ?LOG_DOC_1(debug). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec debug(String :: unicode:chardata()) -> ok; (Report :: report()) -> ok. debug(StringOrReport) -> log(debug,StringOrReport). -doc ?LOG_DOC_2("debug"). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec debug(String :: unicode:chardata(), Metadata :: metadata()) -> ok; (Report :: report(), Metadata :: metadata()) -> ok; (Format :: io:format(), Args :: [term()]) -> ok; @@ -515,14 +511,14 @@ debug(StringOrReport) -> debug(FormatOrFun,Args) -> log(debug,FormatOrFun,Args). -doc ?LOG_DOC_3(debug). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec debug(Format :: io:format(), Args :: [term()], Metadata :: metadata()) -> ok; (Fun :: msg_fun(), FunArgs :: term(), Metadata :: metadata()) -> ok. debug(FormatOrFun,Args,Metadata) -> log(debug,FormatOrFun,Args,Metadata). -doc(#{equiv => log(Level, StringOrReport, #{})}). --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec log(Level :: level(), String :: unicode:chardata()) -> ok; (Level :: level(), Report :: report()) -> ok. log(Level, StringOrReport) -> @@ -549,7 +545,7 @@ the given [message](logger_chapter.md#log-message) to be logged and Equivalent to [`log(Level, FormatOrFun, Args, #{})`](`log/4`) if called as `log(Level, FormatOrFun, Args)`. """. --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec log(Level :: level(), String :: unicode:chardata(), Metadata :: metadata()) -> ok; (Level :: level(), Report :: report(), Metadata :: metadata()) -> ok; (Level :: level(), Format :: io:format(), Args :: [term()]) -> ok; @@ -585,7 +581,7 @@ When metadata is given both as an argument and returned from the fun they are merged. If equal keys exists the values are taken from the metadata returned by the fun. """. --doc(#{title => <<"Logging API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Logging API functions">>,since => <<"OTP 21.0">>}). -spec log(Level :: level(), Format :: io:format(), Args :: [term()], Metadata :: metadata()) -> ok; (Level :: level(), Fun :: msg_fun(), FunArgs :: term(), Metadata :: metadata()) -> ok. log(Level, FunOrFormat, Args, Metadata) -> @@ -666,7 +662,7 @@ printed with `~ts` and other terms with `~tp`. If `Report` is a map, it is converted to a key-value list before formatting as such. """. --doc(#{title => <<"Miscellaneous API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Miscellaneous API functions">>,since => <<"OTP 21.0">>}). -spec format_report(Report) -> FormatArgs when Report :: report(), FormatArgs :: {io:format(),[term()]}. @@ -725,7 +721,7 @@ Notice that Logger automatically inserts a timestamp in the meta data unless it already exists. This function is exported for the rare case when the timestamp must be taken at a different point in time than when the log event is issued. """. --doc(#{title => <<"Miscellaneous API functions">>,since => <<"OTP 21.3">>}). +-doc(#{group => <<"Miscellaneous API functions">>,since => <<"OTP 21.3">>}). -spec timestamp() -> timestamp(). timestamp() -> os:system_time(microsecond). @@ -758,7 +754,7 @@ information about filters. Some built-in filters exist. These are defined in `m:logger_filters`. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec add_primary_filter(FilterId,Filter) -> ok | {error,term()} when FilterId :: filter_id(), Filter :: filter(). @@ -792,7 +788,7 @@ information about filters. Some built-in filters exist. These are defined in `m:logger_filters`. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec add_handler_filter(HandlerId,FilterId,Filter) -> ok | {error,term()} when HandlerId :: logger_handler:id(), FilterId :: filter_id(), @@ -802,7 +798,7 @@ add_handler_filter(HandlerId,FilterId,Filter) -> -doc "Remove the primary filter identified by `FilterId` from Logger.". --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec remove_primary_filter(FilterId) -> ok | {error,term()} when FilterId :: filter_id(). remove_primary_filter(FilterId) -> @@ -812,7 +808,7 @@ remove_primary_filter(FilterId) -> Remove the filter identified by `FilterId` from the handler identified by `HandlerId`. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec remove_handler_filter(HandlerId,FilterId) -> ok | {error,term()} when HandlerId :: logger_handler:id(), FilterId :: filter_id(). @@ -825,7 +821,7 @@ Add a handler with the given configuration. `HandlerId` is a unique identifier which must be used in all subsequent calls referring to this handler. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec add_handler(HandlerId,Module,Config) -> ok | {error,term()} when HandlerId :: logger_handler:id(), Module :: module(), @@ -834,7 +830,7 @@ add_handler(HandlerId,Module,Config) -> logger_server:add_handler(HandlerId,Module,Config). -doc "Remove the handler identified by `HandlerId`.". --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec remove_handler(HandlerId) -> ok | {error,term()} when HandlerId :: logger_handler:id(). remove_handler(HandlerId) -> @@ -847,7 +843,7 @@ exist, it will be added. The `metadata` key was added in OTP 24.0. """. --doc(#{title => <<"Configuration API functions">>, +-doc(#{group => <<"Configuration API functions">>, since => <<"OTP 21.0">>}). -spec set_primary_config(level,Level) -> ok | {error,term()} when Level :: level() | all | none; @@ -872,7 +868,7 @@ writing the new configuration back with this function. If a key is removed compared to the current configuration, the default value is used. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec set_primary_config(Config) -> ok | {error,term()} when Config :: primary_config(). set_primary_config(Config) -> @@ -893,7 +889,7 @@ existing configuration for the rest, use `update_handler_config/3`. See the definition of the `t:logger_handler:config/0` type for more information about the different parameters. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec set_handler_config(HandlerId,level,Level) -> Return when HandlerId :: logger_handler:id(), Level :: level() | all | none, @@ -931,7 +927,7 @@ by Logger, the default value is used. If it is a custom key, then it is up to the handler implementation if the value is removed or a default value is inserted. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec set_handler_config(HandlerId,Config) -> ok | {error,term()} when HandlerId :: logger_handler:id(), Config :: logger_handler:config(). @@ -951,7 +947,7 @@ the new configuration back with this function. For more information about the proxy, see section [Logger Proxy](logger_chapter.md#logger-proxy) in the Kernel User's Guide. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.3">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.3">>}). -spec set_proxy_config(Config) -> ok | {error,term()} when Config :: olp_config(). set_proxy_config(Config) -> @@ -969,7 +965,7 @@ logger:set_primary_config(maps:merge(Old, Config)). To overwrite the existing configuration without any merge, use [`set_primary_config/1` ](`set_primary_config/1`). """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec update_primary_config(Config) -> ok | {error,term()} when Config :: primary_config(). update_primary_config(Config) -> @@ -989,7 +985,7 @@ key is not changed. To reset unspecified data to default values, use See the definition of the `t:logger_handler:config/0` type for more information about the different parameters. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.2">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.2">>}). -spec update_handler_config(HandlerId,level,Level) -> Return when HandlerId :: logger_handler:id(), Level :: level() | all | none, @@ -1025,7 +1021,7 @@ logger:set_handler_config(HandlerId, maps:merge(Old, Config)). To overwrite the existing configuration without any merge, use [`set_handler_config/2` ](`set_handler_config/2`). """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec update_handler_config(HandlerId,Config) -> ok | {error,term()} when HandlerId :: logger_handler:id(), Config :: logger_handler:config(). @@ -1047,14 +1043,14 @@ To overwrite the existing configuration without any merge, use For more information about the proxy, see section [Logger Proxy](logger_chapter.md#logger-proxy) in the Kernel User's Guide. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.3">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.3">>}). -spec update_proxy_config(Config) -> ok | {error,term()} when Config :: olp_config(). update_proxy_config(Config) -> logger_server:update_config(proxy,Config). -doc "Look up the current primary configuration for Logger.". --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec get_primary_config() -> Config when Config :: primary_config(). get_primary_config() -> @@ -1062,7 +1058,7 @@ get_primary_config() -> maps:remove(handlers,Config). -doc "Look up the current configuration for the given handler.". --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec get_handler_config(HandlerId) -> {ok,Config} | {error,term()} when HandlerId :: logger_handler:id(), Config :: logger_handler:config(). @@ -1077,7 +1073,7 @@ get_handler_config(HandlerId) -> end. -doc "Look up the current configuration for all handlers.". --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec get_handler_config() -> [Config] when Config :: logger_handler:config(). get_handler_config() -> @@ -1087,7 +1083,7 @@ get_handler_config() -> end || HandlerId <- get_handler_ids()]. -doc "Look up the identities for all installed handlers.". --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec get_handler_ids() -> [HandlerId] when HandlerId :: logger_handler:id(). get_handler_ids() -> @@ -1100,7 +1096,7 @@ Look up the current configuration for the Logger proxy. For more information about the proxy, see section [Logger Proxy](logger_chapter.md#logger-proxy) in the Kernel User's Guide. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.3">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.3">>}). -spec get_proxy_config() -> Config when Config :: olp_config(). get_proxy_config() -> @@ -1119,7 +1115,7 @@ set_handler_config(HandlerId, formatter, {FormatterModule, FormatterConfig}). ``` """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec update_formatter_config(HandlerId,FormatterConfig) -> ok | {error,term()} when HandlerId :: logger_handler:id(), @@ -1128,7 +1124,7 @@ update_formatter_config(HandlerId,FormatterConfig) -> logger_server:update_formatter_config(HandlerId,FormatterConfig). -doc(#{ equiv => update_formatter_config(HandlerId, #{ Key => Value })}). --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec update_formatter_config(HandlerId,Key,Value) -> ok | {error,term()} when HandlerId :: logger_handler:id(), @@ -1171,7 +1167,7 @@ To change the log level for a handler, use > logging client must explicitly add this information if module levels shall > have any effect. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec set_module_level(Modules,Level) -> ok | {error,term()} when Modules :: [module()] | module(), Level :: level() | all | none. @@ -1184,7 +1180,7 @@ set_module_level(Modules,Level) -> Remove module specific log settings. After this, the primary log level is used for the specified modules. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec unset_module_level(Modules) -> ok when Modules :: [module()] | module(). unset_module_level(Module) when is_atom(Module) -> @@ -1196,7 +1192,7 @@ unset_module_level(Modules) -> Remove module specific log settings. After this, the primary log level is used for all modules. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec unset_module_level() -> ok. unset_module_level() -> logger_server:unset_module_level(). @@ -1208,7 +1204,7 @@ This function is a convenience function that calls [logger:set_module_level/2](`set_module_level/2`) for each module associated with an application. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.1">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.1">>}). -spec set_application_level(Application,Level) -> ok | {error, not_loaded} when Application :: atom(), Level :: level() | all | none. @@ -1227,7 +1223,7 @@ This function is a utility function that calls [logger:unset_module_level/2](`unset_module_level/1`) for each module associated with an application. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.1">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.1">>}). -spec unset_application_level(Application) -> ok | {error, {not_loaded, Application}} when Application :: atom(). unset_application_level(App) -> @@ -1243,7 +1239,7 @@ Look up the current level for the given modules. Returns a list containing one `{Module,Level}` element for each of the given modules for which the module level was previously set with `set_module_level/2`. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec get_module_level(Modules) -> [{Module,Level}] when Modules :: [Module] | Module, Module :: module(), @@ -1259,7 +1255,7 @@ Look up all current module levels. Returns a list containing one `{Module,Level}` element for each module for which the module level was previously set with `set_module_level/2`. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec get_module_level() -> [{Module,Level}] when Module :: module(), Level :: level() | all | none. @@ -1273,7 +1269,7 @@ Compare the severity of two log levels. Returns `gt` if `Level1` is more severe than `Level2`, `lt` if `Level1` is less severe, and `eq` if the levels are equal. """. --doc(#{title => <<"Miscellaneous API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Miscellaneous API functions">>,since => <<"OTP 21.0">>}). -spec compare_levels(Level1,Level2) -> eq | gt | lt when Level1 :: level() | all | none, Level2 :: level() | all | none. @@ -1301,7 +1297,7 @@ location data. Subsequent calls to this function overwrites previous data set. To update existing data instead of overwriting it, see `update_process_metadata/1`. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec set_process_metadata(Meta) -> ok when Meta :: metadata(). set_process_metadata(Meta) when is_map(Meta) -> @@ -1323,7 +1319,7 @@ logger:set_process_metadata(maps:merge(logger:get_process_metadata(), Meta)). If no process metadata exists, the function behaves as [`set_process_metadata/1` ](`set_process_metadata/1`). """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec update_process_metadata(Meta) -> ok when Meta :: metadata(). update_process_metadata(Meta) when is_map(Meta) -> @@ -1338,14 +1334,14 @@ update_process_metadata(Meta) -> erlang:error(badarg,[Meta]). -doc "Retrieve data set with `set_process_metadata/1` or `update_process_metadata/1`.". --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec get_process_metadata() -> Meta | undefined when Meta :: metadata(). get_process_metadata() -> get(?LOGGER_META_KEY). -doc "Delete data set with `set_process_metadata/1` or `update_process_metadata/1`.". --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec unset_process_metadata() -> ok. unset_process_metadata() -> _ = erase(?LOGGER_META_KEY), @@ -1355,7 +1351,7 @@ unset_process_metadata() -> Look up all current Logger configuration, including primary, handler, and proxy configuration, and module level settings. """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec get_config() -> #{primary=>primary_config(), handlers=>[logger_handler:config()], proxy=>olp_config(), @@ -1367,7 +1363,7 @@ get_config() -> module_levels=>lists:keysort(1,get_module_level())}. -doc "Pretty print all Logger configuration.". --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.3">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.3">>}). -spec i() -> ok. i() -> #{primary := Primary, @@ -1381,7 +1377,7 @@ i() -> i_modules(Modules,M). -doc "Pretty print the Logger configuration.". --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.3">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.3">>}). -spec i(What) -> ok when What :: primary | handlers | proxy | modules | logger_handler:id(). i(primary) -> @@ -1513,7 +1509,7 @@ Reconfigure Logger using updated `kernel` configuration that was set after Beware, that this is meant to be run only by the build tools, not manually during application lifetime, as this may cause missing log entries. """. --doc(#{title => <<"Miscellaneous API functions">>,since => <<"OTP 24.2">>}). +-doc(#{group => <<"Miscellaneous API functions">>,since => <<"OTP 24.2">>}). -spec reconfigure() -> ok | {error,term()}. %% This function is meant to be used by the build tools like Rebar3 or Mix %% to ensure that the logger configuration is reset to the expected state @@ -1636,7 +1632,7 @@ that disables the Kernel handler and adds a custom handler could look like this: [{handler, default, my_handler, #{}}]}]}]. ``` """. --doc(#{title => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Configuration API functions">>,since => <<"OTP 21.0">>}). -spec add_handlers(Application) -> ok | {error,term()} when Application :: atom(); (HandlerConfig) -> ok | {error,term()} when diff --git a/lib/kernel/src/logger_formatter.erl b/lib/kernel/src/logger_formatter.erl index edeb0dd4a19e..ba3003cda63f 100644 --- a/lib/kernel/src/logger_formatter.erl +++ b/lib/kernel/src/logger_formatter.erl @@ -36,8 +36,7 @@ information. `m:calendar`, `m:error_logger`, `m:io`, `m:io_lib`, `m:logger`, `m:maps`, [`sasl(6)`](`e:sasl:sasl_app.md`), `m:unicode` """. --moduledoc(#{since => "OTP 21.0", - titles => [{callback,<<"Formatter Callback Functions">>}]}). +-moduledoc(#{since => "OTP 21.0"}). -export([format/2]). -export([check_config/1]). @@ -251,7 +250,7 @@ The following Logger API functions can trigger this callback: See `m:logger_formatter` for an example implementation. `m:logger_formatter` is the default formatter used by Logger. """. --doc(#{title => <<"Formatter Callback Functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Formatter Callback Functions">>,since => <<"OTP 21.0">>}). -callback check_config(FConfig) -> ok | {error, Reason} when FConfig :: logger:formatter_config(), Reason :: term(). @@ -264,7 +263,7 @@ to the console or a file using [`io:put_chars/1,2`](`io:put_chars/1`). See `m:logger_formatter` for an example implementation. `m:logger_formatter` is the default formatter used by Logger. """. --doc(#{title => <<"Formatter Callback Functions">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Formatter Callback Functions">>,since => <<"OTP 21.0">>}). -callback format(LogEvent, FConfig) -> FormattedLogEntry when LogEvent :: logger:log_event(), FConfig :: logger:formatter_config(), diff --git a/lib/kernel/test/interactive_shell_SUITE.erl b/lib/kernel/test/interactive_shell_SUITE.erl index 90b6d7e10ca8..16609e85535e 100644 --- a/lib/kernel/test/interactive_shell_SUITE.erl +++ b/lib/kernel/test/interactive_shell_SUITE.erl @@ -1251,13 +1251,13 @@ shell_expand_location_below(Config) -> send_tty(Term, "escript:"), send_tty(Term, "\t"), %% Cursor at correct place - check_location(Term, {-3, width("escript:")}), + check_location(Term, {-2, width("escript:")}), %% Nothing after the start( completion check_content(Term, "start\\($"), %% Check that completion is cleared when we type send_tty(Term, "s"), - check_location(Term, {-3, width("escript:s")}), + check_location(Term, {-2, width("escript:s")}), check_content(Term, "escript:s$"), %% Check that completion works when in the middle of a term @@ -1267,7 +1267,7 @@ shell_expand_location_below(Config) -> send_tty(Term, ", test_after]"), [send_tty(Term, "Left") || _ <- ", test_after]"], send_tty(Term, "\t"), - check_location(Term, {-3, width("[escript:s")}), + check_location(Term, {-2, width("[escript:s")}), check_content(Term, "script_name\\([ ]+start\\($"), send_tty(Term, "C-K"), @@ -1291,7 +1291,7 @@ shell_expand_location_below(Config) -> Rows1 = 48, send_tty(Term, "long_module:" ++ FunctionName), send_tty(Term, "\t"), - check_content(Term, "3> long_module:" ++ FunctionName ++ "\nfunctions(\n|.)*a_long_function_name0\\("), + check_content(Term, "3> long_module:" ++ FunctionName ++ "\nFunctions(\n|.)*a_long_function_name0\\("), %% Check that correct text is printed below expansion check_content(Term, io_lib:format("rows ~w to ~w of ~w", @@ -1330,7 +1330,7 @@ shell_expand_location_below(Config) -> tmux(["resize-window -t ", tty_name(Term), " -y ", integer_to_list(Row+10)]), timer:sleep(1000), %% Sleep to make sure window has resized send_tty(Term, "\t\t"), - check_content(Term, "3> long_module:" ++ FunctionName ++ "\nfunctions(\n|.)*a_long_function_name99\\($"), + check_content(Term, "3> long_module:" ++ FunctionName ++ "\nFunctions(\n|.)*a_long_function_name99\\($"), %% Check that doing an expansion when cursor is in xnfix position works send_tty(Term, "BSpace"), @@ -1342,7 +1342,7 @@ shell_expand_location_below(Config) -> send_tty(Term, "\t"), check_location(Term, {-Rows + 2, -Col}), send_tty(Term, "\t"), - check_content(Term, "3> a+, long_module:" ++ FunctionName ++ "\n\nfunctions(\n|.)*a_long_function_name0\\("), + check_content(Term, "3> a+, long_module:" ++ FunctionName ++ "\n\nFunctions(\n|.)*a_long_function_name0\\("), check_location(Term, {-Rows + 2, -Col}), send_tty(Term, "Down"), check_location(Term, {-Rows + 2, -Col}), @@ -1353,7 +1353,7 @@ shell_expand_location_below(Config) -> send_tty(Term, lists:duplicate(Cols, "b")), send_tty(Term, "End"), send_tty(Term, "\t"), - check_content(Term, "3> b+\nb+a+, long_module:" ++ FunctionName ++ "\n\nfunctions(\n|.)*a_long_function_name0\\("), + check_content(Term, "3> b+\nb+a+, long_module:" ++ FunctionName ++ "\n\nFunctions(\n|.)*a_long_function_name0\\("), check_location(Term, {-Rows + 3, -Col}), send_tty(Term, "Down"), check_location(Term, {-Rows + 3, -Col}), diff --git a/lib/odbc/src/odbc.erl b/lib/odbc/src/odbc.erl index 27381fba2008..bde01c740a7b 100644 --- a/lib/odbc/src/odbc.erl +++ b/lib/odbc/src/odbc.erl @@ -54,7 +54,6 @@ Erlang ODBC [User's Guide.](error_handling.md) \[1]: Microsoft ODBC 3.0, Programmer's Reference and SDK Guide See also http://msdn.microsoft.com/ """. --moduledoc(#{titles => [{type,<<"Types used in ODBC application">>}]}). -behaviour(gen_server). @@ -80,38 +79,38 @@ See also http://msdn.microsoft.com/ terminate/2, code_change/3]). -doc "Opaque reference to an ODBC connection as returnded by connect/2.". --doc(#{title => <<"Types used in ODBC application">>}). +-doc(#{group => <<"Types used in ODBC application">>}). -opaque connection_reference() :: pid(). -doc "Name of column in the result set.". --doc(#{title => <<"Types used in ODBC application">>}). +-doc(#{group => <<"Types used in ODBC application">>}). -type col_name() :: string(). -doc """ A tuple, with the number of elements selected form columns in a database row, containg the values of the columns such as `{value(), value() ... value()} `. """. --doc(#{title => <<"Types used in ODBC application">>}). +-doc(#{group => <<"Types used in ODBC application">>}). -type row() :: tuple(). -doc "Erlang data type that corresponds to the ODBC data type being handled.". --doc(#{title => <<"Types used in ODBC application">>}). +-doc(#{group => <<"Types used in ODBC application">>}). -type value() :: null | term(). -doc "Return value for queries that select data from database tabels.". --doc(#{title => <<"Types used in ODBC application">>}). +-doc(#{group => <<"Types used in ODBC application">>}). -type selected() :: {selected, [col_name()], [row()]}. -doc "Return value for queries that update database tables.". --doc(#{title => <<"Types used in ODBC application">>}). +-doc(#{group => <<"Types used in ODBC application">>}). -type updated() :: {updated, n_rows()}. -doc """ The number of affected rows for UPDATE, INSERT, or DELETE queries. For other query types the value is driver defined, and hence should be ignored. """. --doc(#{title => <<"Types used in ODBC application">>}). +-doc(#{group => <<"Types used in ODBC application">>}). -type n_rows() :: integer(). -doc """ Data type used by ODBC, to learn which Erlang data type corresponds to an ODBC data type see the Erlang to ODBC data type [mapping](databases.md#type) in the User's Guide. """. --doc(#{title => <<"Types used in ODBC application">>}). +-doc(#{group => <<"Types used in ODBC application">>}). -type odbc_data_type() :: sql_integer | sql_smallint | sql_tinyint | {sql_decimal, Precision::integer(), Scale::integer()} | {sql_numeric, Precision::integer(), Scale::integer()} | @@ -127,13 +126,13 @@ User's Guide. An explanation of what went wrong. For common errors there will be atom decriptions. """. --doc(#{title => <<"Types used in ODBC application">>}). +-doc(#{group => <<"Types used in ODBC application">>}). -type common_reason() :: connection_closed | extended_error() | term(). -doc """ extended error type with ODBC and native database error codes, as well as the base reason that would have been returned had extended_errors not been enabled. """. --doc(#{title => <<"Types used in ODBC application">>}). +-doc(#{group => <<"Types used in ODBC application">>}). -type extended_error() :: {string(), integer(), term()}. -export_type([connection_reference/0, diff --git a/lib/parsetools/src/leex.erl b/lib/parsetools/src/leex.erl index 27b401f4a01c..f1078e1b8eb0 100644 --- a/lib/parsetools/src/leex.erl +++ b/lib/parsetools/src/leex.erl @@ -240,7 +240,6 @@ Floats (\+|-)?[0-9]+\.[0-9]+((E|e)(\+|-)?[0-9]+)? > Anchoring a regular expression with `^` and `$` is not implemented in the > current version of `leex` and generates a parse error. """. --moduledoc(#{titles => [{function,<<"Generated Scanner Exports">>}]}). -export([compile/3,file/1,file/2,format_error/1]). @@ -281,7 +280,7 @@ Floats (\+|-)?[0-9]+\.[0-9]+((E|e)(\+|-)?[0-9]+)? %%% -export([string/1, string/2, token/2, token/3, tokens/2, tokens/3]). -doc #{equiv => string(String, 1)}. --doc(#{title => <<"Generated Scanner Exports">>}). +-doc(#{group => <<"Generated Scanner Exports">>}). -spec string(String) -> StringRet when String :: string(), StringRet :: {ok, Tokens, EndLoc} | ErrorInfo, @@ -301,7 +300,7 @@ or [`erl_anno:location()`](`t:erl_anno:location/0`), depending on the > > It is an error if not all of the characters in `String` are consumed. """. --doc(#{title => <<"Generated Scanner Exports">>}). +-doc(#{group => <<"Generated Scanner Exports">>}). -spec string(String, StartLoc) -> StringRet when String :: string(), StringRet :: {ok, Tokens, EndLoc} | ErrorInfo, @@ -313,7 +312,7 @@ or [`erl_anno:location()`](`t:erl_anno:location/0`), depending on the string(_String, _StartLoc) -> erlang:nif_error(undef). -doc #{equiv => token(Cont, Chars, 1)}. --doc(#{title => <<"Generated Scanner Exports">>}). +-doc(#{group => <<"Generated Scanner Exports">>}). -spec token(Cont, Chars) -> {more, Cont1} | {done, TokenRet, RestChars} when Cont :: [] | Cont1, @@ -347,7 +346,7 @@ io:request(InFile, {get_until,unicode,Prompt,Module,token,[Loc]}) -> TokenRet ``` """. --doc(#{title => <<"Generated Scanner Exports">>}). +-doc(#{group => <<"Generated Scanner Exports">>}). -spec token(Cont, Chars, StartLoc) -> {more, Cont1} | {done, TokenRet, RestChars} when Cont :: [] | Cont1, @@ -364,7 +363,7 @@ io:request(InFile, {get_until,unicode,Prompt,Module,token,[Loc]}) token(_Cont, _Chars, _StartLoc) -> erlang:nif_error(undef). -doc #{equiv => tokens(Cont, Chars, 1)}. --doc(#{title => <<"Generated Scanner Exports">>}). +-doc(#{group => <<"Generated Scanner Exports">>}). -spec tokens(Cont, Chars) -> {more, Cont1} | {done, TokensRet, RestChars} when Cont :: [] | Cont1, @@ -404,7 +403,7 @@ io:request(InFile, {get_until,unicode,Prompt,Module,tokens,[Loc]}) -> TokensRet ``` """. --doc(#{title => <<"Generated Scanner Exports">>}). +-doc(#{group => <<"Generated Scanner Exports">>}). -spec tokens(Cont, Chars, StartLoc) -> {more, Cont1} | {done, TokensRet, RestChars} when Cont :: [] | Cont1, diff --git a/lib/public_key/src/public_key.erl b/lib/public_key/src/public_key.erl index af359c539423..d6142fb615a6 100644 --- a/lib/public_key/src/public_key.erl +++ b/lib/public_key/src/public_key.erl @@ -41,22 +41,6 @@ macros described here and in the User's Guide: ``` """. --moduledoc(#{titles => - [{type, <<"Common">>}, - {type,<<"Keys">>}, - {type,<<"PEM files">>}, - {type,<<"Certificates">>}, - {type,<<"Certificate Revocation">>}, - {type,<<"Test Data">>}, - {function,<<"PEM API">>}, - {function,<<"Key API">>}, - {function,<<"Sign/Verify API">>}, - {function,<<"Certificate API">>}, - {function,<<"Certificate Revocation API">>}, - {function,<<"ASN.1 Encoding API">>}, - {function,<<"Test Data API">>}, - {function,<<"Legacy RSA Encryption API">>} - ]}). -feature(maybe_expr,enable). -include("public_key.hrl"). @@ -168,14 +152,14 @@ macros described here and in the User's Guide: {crypto, public_decrypt, 4} ]}). --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -doc "Supported public keys". -type public_key() :: rsa_public_key() | rsa_pss_public_key() | dsa_public_key() | ecdsa_public_key() | eddsa_public_key() . --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -doc "Supported private keys". -type private_key() :: rsa_private_key() | rsa_pss_private_key() | @@ -184,72 +168,72 @@ macros described here and in the User's Guide: eddsa_private_key() | #{algorithm := eddsa | rsa_pss_pss | ecdsa | rsa | dsa, sign_fun => fun()} . --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -doc """ Can be provided together with a custom private key, that specifies a key fun, to provide additional options understood by the fun. """. -type custom_key_opts() :: [term()]. --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -doc "ASN.1 defined public key format for plain RSA algorithm.". -type rsa_public_key() :: #'RSAPublicKey'{}. --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -doc "ASN.1 defined private key format plain RSA algorithm or customization fun.". -type rsa_private_key() :: #'RSAPrivateKey'{} | #{algorithm := rsa, encrypt_fun => fun()}. --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -doc "ASN.1 defined public key format for the RSSASSA-PSS algorithm.". -type rsa_pss_public_key() :: {rsa_public_key(), #'RSASSA-PSS-params'{}}. --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -doc "ASN.1 defined private key format the RSSASSA-PSS algorithm or customization fun.". -type rsa_pss_private_key() :: { #'RSAPrivateKey'{}, #'RSASSA-PSS-params'{}}. --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -doc "ASN.1 defined private key format for the DSA algorithm.". -type dsa_private_key() :: #'DSAPrivateKey'{}. --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -doc "ASN.1 defined public key format for the DSA algorithm.". -type dsa_public_key() :: {dss_public_key(), #'Dss-Parms'{}}. --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -doc "ASN.1 defined public key format for the DSS algorithm (part of DSA key).". -type dss_public_key() :: pos_integer(). --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -doc "ASN.1 defined public key format for the ECDSA algorithm.". -type ecdsa_public_key() :: {#'ECPoint'{},{namedCurve, oid()} | #'ECParameters'{}}. --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -doc "ASN.1 defined private key format for the ECDSA algorithm.". -type ecdsa_private_key() :: #'ECPrivateKey'{}. --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -doc """ ASN.1 defined public key format for the EDDSA algorithm, possible oids: ?'id-Ed25519' | ?'id-Ed448' """. -type eddsa_public_key() :: {#'ECPoint'{}, {namedCurve, oid()}}. --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -doc """ ASN.1 defined private key format for the EDDSA algorithm, possible oids: ?'id-Ed25519' | ?'id-Ed448' """. -type eddsa_private_key() :: #'ECPrivateKey'{parameters :: {namedCurve, oid()}}. --doc(#{title => <<"Keys">>}). +-doc(#{group => <<"Keys">>}). -doc "ASN.1 defined parameters for public key algorithms.". -type key_params() :: 'NULL' | #'RSASSA-PSS-params'{} | {namedCurve, oid()} | #'ECParameters'{} | #'Dss-Parms'{}. --doc(#{title => <<"Common">>}). +-doc(#{group => <<"Common">>}). -doc """ ASN.1 DER encoded entity. """. -type der_encoded() :: binary(). --doc(#{title => <<"PEM files">>}). +-doc(#{group => <<"PEM files">>}). -doc """ ASN.1 type that can be found in PEM files that can be decode by the public_key application. """. @@ -259,7 +243,7 @@ ASN.1 type that can be found in PEM files that can be decode by the public_key a 'CertificationRequest' | 'ContentInfo' | 'CertificateList' | 'ECPrivateKey' | 'OneAsymmetricKey'| 'EcpkParameters'. --doc(#{title => <<"PEM files">>}). +-doc(#{group => <<"PEM files">>}). -doc """ Possible `Ciphers` are "RC2-CBC" | "DES-CBC" | "DES-EDE3-CBC" `Salt` could be generated with [`crypto:strong_rand_bytes(8)`](`crypto:strong_rand_bytes/1`). @@ -271,38 +255,38 @@ Possible `Ciphers` are "RC2-CBC" | "DES-CBC" | "DES-EDE3-CBC" `Salt` could be ge | #'PBES2-params'{}} }. --doc(#{title => <<"Common">>}). +-doc(#{group => <<"Common">>}). -doc "ASN.1 type present in the Public Key applications ASN.1 specifications.". -type asn1_type() :: atom(). %% see "OTP-PUB-KEY.hrl --doc(#{title => <<"Common">>}). +-doc(#{group => <<"Common">>}). -doc "Hash function used to create a message digest". -type digest_type() :: crypto:sha2() | crypto:sha1() | md5 | none. --doc(#{title => <<"Certificate Revocation">>}). +-doc(#{group => <<"Certificate Revocation">>}). -doc """ The reason that a certifcate has been revoked as define by RFC 5280. """. -type crl_reason() :: unspecified | keyCompromise | cACompromise | affiliationChanged | superseded | cessationOfOperation | certificateHold | privilegeWithdrawn | aACompromise. --doc(#{title => <<"Common">>}). +-doc(#{group => <<"Common">>}). -doc "Object identifier, a tuple of integers as generated by the `ASN.1` compiler.". -type oid() :: tuple(). --doc(#{title => <<"Certificates">>}). +-doc(#{group => <<"Certificates">>}). -doc """ A certificate is identified by its serial-number and Issuer Name. """. -type cert_id() :: {SerialNr::integer(), issuer_name()} . --doc(#{title => <<"Certificates">>}). +-doc(#{group => <<"Certificates">>}). -doc """ The value of the issuer part of a certificate. """. -type issuer_name() :: {rdnSequence,[[#'AttributeTypeAndValue'{}]]} . --doc(#{title => <<"Certificates">>}). +-doc(#{group => <<"Certificates">>}). -doc """ The reason that a certifcate gets rejected by the certificate path validation. """. @@ -313,7 +297,7 @@ The reason that a certifcate gets rejected by the certificate path validation. {revoked, crl_reason()} | invalid_validity_dates | {revocation_status_undetermined, term()} | atom(). --doc(#{title => <<"Certificates">>}). +-doc(#{group => <<"Certificates">>}). -doc """ A record that can be used to provide the certificate on both the DER encoded and the OTP decode format. @@ -321,18 +305,18 @@ Such a construct can be useful to avoid conversions and problems that can arise """. -type combined_cert() :: #cert{}. --doc(#{title => <<"Certificates">>}). +-doc(#{group => <<"Certificates">>}). -doc "An encoded or decode certificate.". -type cert() :: der_encoded() | #'OTPCertificate'{}. --doc(#{title => <<"Certificates">>}). +-doc(#{group => <<"Certificates">>}). -doc "Certificate policy information.". -type policy_node() :: #{valid_policy := oid(), qualifier_set := [#'UserNotice'{}| {uri, string()}], expected_policy_set := [oid()]}. --doc(#{title => <<"Certificates">>}). +-doc(#{group => <<"Certificates">>}). -doc """ Information a certificates public key. @@ -340,7 +324,7 @@ Possible oids: ?'rsaEncryption' | ?'id-RSASSA-PSS' | ?'id-ecPublicKey' | ?'id-Ed """. -type public_key_info() :: {oid(), rsa_public_key() | #'ECPoint'{} | dss_public_key(), key_params()}. --doc(#{title => <<"Test Data">>}). +-doc(#{group => <<"Test Data">>}). -doc """ Options to customize generated test certificates """. @@ -349,7 +333,7 @@ Options to customize generated test certificates {validity, {From::erlang:timestamp(), To::erlang:timestamp()}} | {extensions, [#'Extension'{}]}. --doc(#{title => <<"Test Data">>}). +-doc(#{group => <<"Test Data">>}). -doc """ Certificate customize options for diffrent parts of the certificate test chain. """. @@ -357,7 +341,7 @@ Certificate customize options for diffrent parts of the certificate test chain. peer := [cert_opt()] }. --doc(#{title => <<"Test Data">>}). +-doc(#{group => <<"Test Data">>}). -doc """ Configuration options for the generated certificate test chain. """. @@ -381,7 +365,7 @@ Configuration options for the generated certificate test chain. %%==================================================================== %%-------------------------------------------------------------------- --doc(#{title => <<"PEM API">>}). +-doc(#{group => <<"PEM API">>}). -doc """ Decodes PEM binary data and returns entries as ASN.1 DER encoded entities. @@ -397,7 +381,7 @@ pem_decode(PemBin) when is_binary(PemBin) -> %%-------------------------------------------------------------------- --doc(#{title => <<"PEM API">>, +-doc(#{group => <<"PEM API">>, since => <<"OTP R14B">>}). -doc "Creates a PEM binary.". -spec pem_encode([pem_entry()]) -> binary(). @@ -406,7 +390,7 @@ pem_encode(PemEntries) when is_list(PemEntries) -> iolist_to_binary(pubkey_pem:encode(PemEntries)). %%-------------------------------------------------------------------- --doc(#{title => <<"PEM API">>, +-doc(#{group => <<"PEM API">>, equiv => pem_entry_decode(PemEntry, ""), since => <<"OTP R14B">>}). -spec pem_entry_decode(PemEntry) -> term() when PemEntry :: pem_entry() . @@ -429,7 +413,7 @@ pem_entry_decode({Asn1Type, Der, not_encrypted}) when is_atom(Asn1Type), is_binary(Der) -> der_decode(Asn1Type, Der). --doc(#{title => <<"PEM API">>, +-doc(#{group => <<"PEM API">>, since => <<"OTP R14B">>}). -doc """ Decodes a PEM entry. [`pem_decode/1`](`pem_decode/1`) returns a list of PEM @@ -467,7 +451,7 @@ pem_entry_decode({Asn1Type, CryptDer, {Cipher, Salt}} = PemEntry, do_pem_entry_decode(PemEntry, Password). %%-------------------------------------------------------------------- --doc(#{title => <<"PEM API">>, +-doc(#{group => <<"PEM API">>, since => <<"OTP R14B">>, equiv => pem_entry_encode/3}). -spec pem_entry_encode(Asn1Type, Entity) -> pem_entry() when Asn1Type :: pki_asn1_type(), @@ -505,7 +489,7 @@ pem_entry_encode(Asn1Type, Entity) when is_atom(Asn1Type) -> Der = der_encode(Asn1Type, Entity), {Asn1Type, Der, not_encrypted}. --doc(#{title => <<"PEM API">>, +-doc(#{group => <<"PEM API">>, since => <<"OTP R14B">>}). -doc """ Creates a PEM entry that can be feed to [`pem_encode/1`](`pem_encode/1`). @@ -543,7 +527,7 @@ pem_entry_encode(Asn1Type, Entity, {{Cipher, Salt} = CipherInfo, do_pem_entry_encode(Asn1Type, Entity, CipherInfo, Password). %%-------------------------------------------------------------------- --doc(#{title => <<"ASN.1 Encoding API">>, +-doc(#{group => <<"ASN.1 Encoding API">>, since => <<"OTP R14B">>}). -doc "Decodes a public-key ASN.1 DER encoded entity.". @@ -644,7 +628,7 @@ der_priv_key_decode(PKCS8Key) -> PKCS8Key. %%-------------------------------------------------------------------- --doc(#{title => <<"ASN.1 Encoding API">>, +-doc(#{group => <<"ASN.1 Encoding API">>, since => <<"OTP R14B">>}). -doc "Encodes a public-key entity with ASN.1 DER encoding.". -spec der_encode(Asn1Type, Entity) -> Der when Asn1Type :: asn1_type(), @@ -748,7 +732,7 @@ der_encode(Asn1Type, Entity) when is_atom(Asn1Type) -> %%-------------------------------------------------------------------- --doc(#{title => <<"Certificate API">>}). +-doc(#{group => <<"Certificate API">>}). -doc """ Decodes an ASN.1 DER-encoded PKIX certificate. @@ -779,7 +763,7 @@ pkix_decode_cert(DerCert, otp) when is_binary(DerCert) -> end. %%-------------------------------------------------------------------- --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP R14B">>}). -doc """ DER encodes a PKIX x509 certificate or part of such a certificate. @@ -815,7 +799,7 @@ pkix_encode(Asn1Type, Term0, otp) when is_atom(Asn1Type) -> %%-------------------------------------------------------------------- -doc(#{equiv => decrypt_private(CipherText, Key, []), - title => <<"Legacy RSA Encryption API">>, + group => <<"Legacy RSA Encryption API">>, since => <<"OTP R14B">>}). -spec decrypt_private(CipherText, Key) -> PlainText when CipherText :: binary(), @@ -824,7 +808,7 @@ pkix_encode(Asn1Type, Term0, otp) when is_atom(Asn1Type) -> decrypt_private(CipherText, Key) -> decrypt_private(CipherText, Key, []). --doc(#{title => <<"Legacy RSA Encryption API">>, +-doc(#{group => <<"Legacy RSA Encryption API">>, since => <<"OTP R14B">>}). -doc """ Public-key decryption using the private key. See also `crypto:private_decrypt/4` @@ -849,7 +833,7 @@ decrypt_private(CipherText, %% Description: Public key decryption using the public key. %%-------------------------------------------------------------------- -doc(#{equiv => decrypt_public(CipherText, Key, []), - title => <<"Legacy RSA Encryption API">>, + group => <<"Legacy RSA Encryption API">>, since => <<"OTP R14B">>}). -spec decrypt_public(CipherText, Key) -> PlainText @@ -859,7 +843,7 @@ decrypt_private(CipherText, decrypt_public(CipherText, Key) -> decrypt_public(CipherText, Key, []). --doc(#{title => <<"Legacy RSA Encryption API">>, +-doc(#{group => <<"Legacy RSA Encryption API">>, since => <<"OTP R14B">>}). -doc """ Public-key decryption using the public key. See also `crypto:public_decrypt/4` @@ -884,7 +868,7 @@ decrypt_public(CipherText, #'RSAPublicKey'{modulus = N, publicExponent = E}, %% Description: Public key encryption using the public key. %%-------------------------------------------------------------------- -doc(#{equiv => encrypt_public(PlainText, Key, []), - title => <<"Legacy RSA Encryption API">>, + group => <<"Legacy RSA Encryption API">>, since => <<"OTP R14B">>}). -spec encrypt_public(PlainText, Key) -> CipherText @@ -894,7 +878,7 @@ decrypt_public(CipherText, #'RSAPublicKey'{modulus = N, publicExponent = E}, encrypt_public(PlainText, Key) -> encrypt_public(PlainText, Key, []). --doc(#{title => <<"Legacy RSA Encryption API">>, +-doc(#{group => <<"Legacy RSA Encryption API">>, since => <<"OTP 21.1">>}). -doc """ Public-key encryption using the public key. See also `crypto:public_encrypt/4`. @@ -915,7 +899,7 @@ encrypt_public(PlainText, #'RSAPublicKey'{modulus=N,publicExponent=E}, %%-------------------------------------------------------------------- -doc(#{equiv => encrypt_private(PlainText, Key, []), - title => <<"Legacy RSA Encryption API">>, + group => <<"Legacy RSA Encryption API">>, since => <<"OTP R14B">>}). -spec encrypt_private(PlainText, Key) -> CipherText @@ -925,7 +909,7 @@ encrypt_public(PlainText, #'RSAPublicKey'{modulus=N,publicExponent=E}, encrypt_private(PlainText, Key) -> encrypt_private(PlainText, Key, []). --doc(#{title => <<"Legacy RSA Encryption API">>, +-doc(#{group => <<"Legacy RSA Encryption API">>, since => <<"OTP 21.1">>}). -doc """ Public-key encryption using the private key. @@ -990,7 +974,7 @@ may be regenerated like this: $> cd ..; make ``` """. --doc(#{title => <<"Key API">>, +-doc(#{group => <<"Key API">>, since => <<"OTP 18.2">>}). -spec dh_gex_group(MinSize, SuggestedSize, MaxSize, Groups) -> {ok,{Size,Group}} | {error,term()} @@ -1012,7 +996,7 @@ dh_gex_group(Min, N, Max, Groups) -> Generates a new key pair. Note that except for Diffie-Hellman the public key is included in the private key structure. See also `crypto:generate_key/2` """. --doc(#{title => <<"Key API">>, +-doc(#{group => <<"Key API">>, since => <<"OTP R16B01">>}). -spec generate_key(DHparams | ECparams | RSAparams) -> DHkeys | ECkey | RSAkey @@ -1073,7 +1057,7 @@ generate_key({rsa, ModulusSize, PublicExponent}) -> %%-------------------------------------------------------------------- %% Description: Compute shared secret %%-------------------------------------------------------------------- --doc(#{title => <<"Key API">>, +-doc(#{group => <<"Key API">>, since => <<"OTP R16B01">>}). -doc "Computes shared secret.". -spec compute_key(OthersECDHkey, MyECDHkey) -> @@ -1092,7 +1076,7 @@ compute_key(#'ECPoint'{point = Point}, #'ECPrivateKey'{privateKey = PrivKey, ECCurve = ec_curve_spec(Param), crypto:compute_key(ecdh, Point, PrivKey, ECCurve). --doc(#{title => <<"Key API">>, +-doc(#{group => <<"Key API">>, since => <<"OTP R16B01">>}). -doc "Computes shared secret.". @@ -1106,7 +1090,7 @@ compute_key(PubKey, PrivKey, #'DHParameter'{prime = P, base = G}) -> crypto:compute_key(dh, PubKey, PrivKey, [P, G]). %%-------------------------------------------------------------------- --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP R16B01">>}). -doc """ Translates signature algorithm OID to Erlang digest and signature types. @@ -1157,7 +1141,7 @@ pkix_sign_types(?'id-Ed448') -> {none, eddsa}. %%-------------------------------------------------------------------- --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP 23.0">>}). -doc "Translates OID to Erlang digest type". -spec pkix_hash_type(HashOid::oid()) -> DigestType:: md5 | crypto:sha1() | crypto:sha2(). @@ -1177,7 +1161,7 @@ pkix_hash_type('id-md5') -> %%-------------------------------------------------------------------- -doc(#{equiv => sign(Msg, DigestType, Key, []), - title => <<"Sign/Verify API">>}). + group => <<"Sign/Verify API">>}). -spec sign(Msg, DigestType, Key) -> Signature when Msg :: binary() | {digest,binary()}, @@ -1196,7 +1180,7 @@ standard key, be a map specifing a key algorithm and a fun that should handle the signing. This may be used for customized signing with for instance hardware security modules (HSM) or trusted platform modules (TPM). """. --doc(#{title => <<"Sign/Verify API">>, +-doc(#{group => <<"Sign/Verify API">>, since => <<"OTP 20.1">>}). -spec sign(Msg, DigestType, Key, Options) -> Signature when Msg :: binary() | {digest,binary()}, @@ -1219,7 +1203,7 @@ sign(DigestOrPlainText, DigestType, Key, Options) -> %%-------------------------------------------------------------------- -doc(#{equiv => verify(Msg, DigestType, Signature, Key, []), - title => <<"Sign/Verify API">>, + group => <<"Sign/Verify API">>, since => <<"OTP R14B">>}). -spec verify(Msg, DigestType, Signature, Key) -> boolean() when Msg :: binary() | {digest, binary()}, @@ -1230,7 +1214,7 @@ sign(DigestOrPlainText, DigestType, Key, Options) -> verify(DigestOrPlainText, DigestType, Signature, Key) -> verify(DigestOrPlainText, DigestType, Signature, Key, []). --doc(#{title => <<"Sign/Verify API">>, +-doc(#{group => <<"Sign/Verify API">>, since => <<"OTP 20.1">>}). -doc """ Verifies a digital signature. @@ -1261,7 +1245,7 @@ verify(_,_,_,_,_) -> false. %%-------------------------------------------------------------------- --doc(#{title => <<"Certificate Revocation API">>, +-doc(#{group => <<"Certificate Revocation API">>, since => <<"OTP 17.5">>}). -doc """ Creates a distribution point for CRLs issued by the same issuer as `Cert`. Can @@ -1292,7 +1276,7 @@ pkix_dist_point(OtpCert) -> distributionPoint = Point}. %%-------------------------------------------------------------------- -doc "Extracts distribution points from the certificates extensions.". --doc(#{title => <<"Certificate Revocation API">>, +-doc(#{group => <<"Certificate Revocation API">>, since => <<"OTP 17.5">>}). -spec pkix_dist_points(Cert) -> DistPoints when Cert :: cert(), DistPoints :: [ #'DistributionPoint'{} ]. @@ -1315,7 +1299,7 @@ Point of the CRL, as described in RFC 5280. If the CRL doesn't have an Issuing Distribution Point extension, the distribution point always matches. """. --doc(#{title => <<"Certificate Revocation API">>, +-doc(#{group => <<"Certificate Revocation API">>, since => <<"OTP 19.0">>}). -spec pkix_match_dist_point(CRL, DistPoint) -> boolean() @@ -1350,7 +1334,7 @@ pkix_match_dist_point(#'CertificateList'{ %%-------------------------------------------------------------------- -doc "Signs an 'OTPTBSCertificate'. Returns the corresponding DER-encoded certificate.". --doc(#{title => <<"Sign/Verify API">>, +-doc(#{group => <<"Sign/Verify API">>, since => <<"OTP R14B">>}). -spec pkix_sign(Cert, Key) -> Der when Cert :: #'OTPTBSCertificate'{}, Key :: private_key(), @@ -1370,7 +1354,7 @@ pkix_sign(#'OTPTBSCertificate'{signature = %%-------------------------------------------------------------------- -doc "Verifies PKIX x.509 certificate signature.". --doc(#{title => <<"Sign/Verify API">>, +-doc(#{group => <<"Sign/Verify API">>, since => <<"OTP R14B">>}). -spec pkix_verify(Cert, Key) -> boolean() when Cert :: der_encoded(), Key :: public_key() . @@ -1409,7 +1393,7 @@ pkix_verify(DerCert, Key = {#'ECPoint'{}, _}) when is_binary(DerCert) -> %%-------------------------------------------------------------------- -doc "Verify that `Cert` is the `CRL` signer.". --doc(#{title => <<"Certificate Revocation API">>, +-doc(#{group => <<"Certificate Revocation API">>, since => <<"OTP 17.5">>}). -spec pkix_crl_verify(CRL, Cert) -> boolean() when CRL :: der_encoded() | #'CertificateList'{}, @@ -1431,7 +1415,7 @@ pkix_crl_verify(#'CertificateList'{} = CRL, #'OTPCertificate'{} = Cert) -> %%-------------------------------------------------------------------- -doc "Checks if `IssuerCert` issued `Cert`.". --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP R14B">>}). -spec pkix_is_issuer(CertorCRL, IssuerCert) -> boolean() when CertorCRL :: cert() | #'CertificateList'{}, @@ -1454,7 +1438,7 @@ pkix_is_issuer(#'CertificateList'{tbsCertList = TBSCRL}, %%-------------------------------------------------------------------- -doc "Checks if a certificate is self-signed.". --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP R14B">>}). -spec pkix_is_self_signed(Cert) -> boolean() when Cert::cert(). %%-------------------------------------------------------------------- @@ -1466,7 +1450,7 @@ pkix_is_self_signed(Cert) when is_binary(Cert) -> %%-------------------------------------------------------------------- -doc "Checks if a certificate is a fixed Diffie-Hellman certificate.". --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP R14B">>}). -spec pkix_is_fixed_dh_cert(Cert) -> boolean() when Cert::cert(). %%-------------------------------------------------------------------- @@ -1478,7 +1462,7 @@ pkix_is_fixed_dh_cert(Cert) when is_binary(Cert) -> %%-------------------------------------------------------------------- -doc "Returns the x509 certificate issuer id, if it can be determined.". --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP R14B">>}). -spec pkix_issuer_id(Cert, IssuedBy) -> {ok, ID::cert_id()} | {error, Reason} @@ -1496,7 +1480,7 @@ pkix_issuer_id(Cert, Signed) when is_binary(Cert) -> %%-------------------------------------------------------------------- -doc "Returns the X509 certificate subject id.". --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP 23.1">>}). -spec pkix_subject_id(Cert) -> ID when Cert::cert(), @@ -1511,7 +1495,7 @@ pkix_subject_id(Cert) when is_binary(Cert) -> %%-------------------------------------------------------------------- -doc "Returns the issuer of the `CRL`.". --doc(#{title => <<"Certificate Revocation API">>, +-doc(#{group => <<"Certificate Revocation API">>, since => <<"OTP 17.5">>}). -spec pkix_crl_issuer(CRL) -> Issuer when CRL :: der_encoded() | #'CertificateList'{}, @@ -1524,7 +1508,7 @@ pkix_crl_issuer(#'CertificateList'{} = CRL) -> CRL#'CertificateList'.tbsCertList#'TBSCertList'.issuer, decode). %%-------------------------------------------------------------------- --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP R14B">>}). -doc """ Normalizes an issuer name so that it can be easily compared to another issuer @@ -1543,7 +1527,7 @@ pkix_normalize_name(Issuer) -> pubkey_cert:normalize_general_name(Issuer). %%-------------------------------------------------------------------- --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP R16B">>}). -doc """ Performs a basic path validation according to @@ -1713,7 +1697,7 @@ pkix_path_validation(PathErr, [Cert0 | Chain], Options0) when is_atom(PathErr)-> {error, Reason} end. %-------------------------------------------------------------------- --doc(#{title => <<"Certificate Revocation API">>, +-doc(#{group => <<"Certificate Revocation API">>, since => <<"OTP R16B">>}). -doc """ Performs CRL validation. It is intended to be called from the verify fun of @@ -1787,7 +1771,7 @@ pkix_crls_validate(OtpCert, DPAndCRLs0, Options) -> %-------------------------------------------------------------------- %% Description: Validates a hostname to RFC 6125 %%-------------------------------------------------------------------- --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, equiv => pkix_verify_hostname(Cert, ReferenceIDs, []), since => <<"OTP 19.3">>}). -spec pkix_verify_hostname(Cert, ReferenceIDs) -> boolean() @@ -1797,7 +1781,7 @@ pkix_crls_validate(OtpCert, DPAndCRLs0, Options) -> pkix_verify_hostname(Cert, ReferenceIDs) -> pkix_verify_hostname(Cert, ReferenceIDs, []). --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP 19.3">>}). -doc """ This function checks that the _Presented Identifier_ (e.g hostname) in a peer @@ -1951,7 +1935,7 @@ rules for the protocol in the argument. > the hostname match the default match function used by ssl application will be > sufficient. """. --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP 21.0">>}). -spec pkix_verify_hostname_match_fun(Protocol) -> Result when Protocol :: https, @@ -1996,7 +1980,7 @@ of a CRL or a certificate, respectively. This hash is used by the `c_rehash` tool to maintain a directory of symlinks to CRL files, in order to facilitate looking up a CRL by its issuer name. """. --doc(#{title => <<"Certificate Revocation API">>, +-doc(#{group => <<"Certificate Revocation API">>, since => <<"OTP 19.0">>}). -spec short_name_hash(Name) -> string() when Name :: issuer_name() . @@ -2085,7 +2069,7 @@ chains: > This function is provided for testing purposes only. """. --doc(#{title => <<"Test Data API">>, +-doc(#{group => <<"Test Data API">>, since => <<"OTP 20.1">>}). -spec pkix_test_data(ChainConf) -> TestConf when ChainConf :: #{server_chain:= chain_opts(), @@ -2112,7 +2096,7 @@ Generates a root certificate that can be used in multiple calls to `pkix_test_data/1` when you want the same root certificate for several generated certificates. """. --doc(#{title => <<"Test Data API">>, +-doc(#{group => <<"Test Data API">>, since => <<"OTP 20.2">>}). -spec pkix_test_root_cert(Name, Options) -> RootCertAndKey @@ -2154,7 +2138,7 @@ Available options: > by the client. In such cases {missing, ocsp_nonce} will be returned > in Details list. """. --doc(#{title => <<"Certificate Revocation API">>, +-doc(#{group => <<"Certificate Revocation API">>, since => <<"OTP 27.0">>}). -spec pkix_ocsp_validate(Cert, IssuerCert, OcspRespDer, NonceExt, Options) -> {ok, Details} | {error, {bad_cert, Reason}} @@ -2213,7 +2197,7 @@ ocsp_extensions(Nonce) -> erlang:is_record(Extn, 'Extension')]. %%-------------------------------------------------------------------- --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP 25.0">>}). -doc """ Returns the trusted CA certificates if any are loaded, otherwise uses @@ -2227,7 +2211,7 @@ cacerts_get() -> pubkey_os_cacerts:get(). %%-------------------------------------------------------------------- --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP 25.0">>}). -doc """ Loads the OS supplied trusted CA certificates. @@ -2251,7 +2235,7 @@ cacerts_load() -> %%-------------------------------------------------------------------- --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP 25.0">>}). -doc "Loads the trusted CA certificates from a file.". -spec cacerts_load(File::file:filename_all()) -> ok | {error, Reason::term()}. @@ -2260,7 +2244,7 @@ cacerts_load(File) -> pubkey_os_cacerts:load([File]). %%-------------------------------------------------------------------- --doc(#{title => <<"Certificate API">>, +-doc(#{group => <<"Certificate API">>, since => <<"OTP 25.0">>}). -doc "Clears any loaded CA certificates, returns true if any was loaded.". -spec cacerts_clear() -> boolean(). diff --git a/lib/sasl/src/release_handler.erl b/lib/sasl/src/release_handler.erl index 597ec16d71dc..55acfb93a8e5 100644 --- a/lib/sasl/src/release_handler.erl +++ b/lib/sasl/src/release_handler.erl @@ -215,7 +215,6 @@ release_handler does. [`config`](`e:kernel:config.md`), [`rel`](rel.md), [`relup`](relup.md), [`script`](script.md), `m:sys`, `m:systools` """. --moduledoc(#{titles => [{function,<<"Application Upgrade/Downgrade">>}]}). -behaviour(gen_server). -include_lib("kernel/include/file.hrl"). @@ -938,7 +937,7 @@ If the `restart_new_emulator` instruction is found in the script, before the rest of the upgrade instructions can be executed, and this can only be done by [`install_release/1,2`](`install_release/1`). """. --doc(#{title => <<"Application Upgrade/Downgrade">>}). +-doc(#{group => <<"Application Upgrade/Downgrade">>}). -spec upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason} when App :: atom(), Dir :: string(), Unpurged :: [Module], @@ -968,7 +967,7 @@ upgrade_app(App, NewDir1) -> %% located in the ebin dir of the _current_ version %%----------------------------------------------------------------- -doc(#{equiv => downgrade_app/3}). --doc(#{title => <<"Application Upgrade/Downgrade">>}). +-doc(#{group => <<"Application Upgrade/Downgrade">>}). -spec downgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason} when App :: atom(), Dir :: string(), @@ -1008,7 +1007,7 @@ Returns one of the following: - `restart_emulator` if this instruction is encountered in the script - `{error, Reason}` if an error occurred when finding or evaluating the script """. --doc(#{title => <<"Application Upgrade/Downgrade">>}). +-doc(#{group => <<"Application Upgrade/Downgrade">>}). -spec downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason} when App :: atom(), Dir :: string(), OldVsn :: string(), @@ -1049,7 +1048,7 @@ application version. For details about `Script`, see [`appup(4)`](appup.md). Failure: If a script cannot be found, the function fails with an appropriate error reason. """. --doc(#{title => <<"Application Upgrade/Downgrade">>}). +-doc(#{group => <<"Application Upgrade/Downgrade">>}). -spec upgrade_script(App, Dir) -> {ok, NewVsn, Script} when App :: atom(), @@ -1098,7 +1097,7 @@ Returns `{ok, Script}` if successful. For details about `Script`, see Failure: If a script cannot be found, the function fails with an appropriate error reason. """. --doc(#{title => <<"Application Upgrade/Downgrade">>}). +-doc(#{group => <<"Application Upgrade/Downgrade">>}). -spec downgrade_script(App, OldVsn, Dir) -> {ok, Script} when App :: atom(), @@ -1144,7 +1143,7 @@ If the `restart_new_emulator` instruction is found in the script, before the rest of the upgrade instructions can be executed, and this can only be done by [`install_release/1,2`](`install_release/1`). """. --doc(#{title => <<"Application Upgrade/Downgrade">>}). +-doc(#{group => <<"Application Upgrade/Downgrade">>}). -spec eval_appup_script(App, ToVsn, ToDir, Script :: term()) -> {ok, Unpurged} | restart_emulator | diff --git a/lib/snmp/src/agent/snmpa_mib_data.erl b/lib/snmp/src/agent/snmpa_mib_data.erl index 197a78e56978..4954c5f600d8 100644 --- a/lib/snmp/src/agent/snmpa_mib_data.erl +++ b/lib/snmp/src/agent/snmpa_mib_data.erl @@ -47,8 +47,7 @@ Note that the data extracted from the imported (loaded) mibs are stored partly by the mib-server and partly by the symbolic-store server. See the default mib-server data module, `snmpa_mib_data_tttn` for details. """. --moduledoc(#{since => "OTP R16B01", - titles => [{callback,<<"CALLBACK FUNCTIONS">>}]}). +-moduledoc(#{since => "OTP R16B01"}). -include_lib("snmp/include/snmp_types.hrl"). @@ -78,13 +77,13 @@ mib-server data module, `snmpa_mib_data_tttn` for details. -doc """ Create a new mib-server data instance. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback new(MibStorage :: snmpa:mib_storage()) -> State :: term(). -doc """ Close the mib-storage. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback close(State :: term()) -> ok. -doc """ @@ -92,7 +91,7 @@ Synchronize (write to disc, if possible) the mib-server data. This depends on the `mib_storage` option, and will only have an effect if the mib-storage option has an actual disc component (such as dets, or ets with a file). """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback sync(State :: term()) -> ok. -doc """ @@ -100,7 +99,7 @@ Load the mib specified by the `Filename` argument into the mib-server. The `MeOverride` and `TeOverride` arguments specifies how the mib-server shall handle duplicate mib- and trap- entries. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback load_mib(State :: term(), FileName :: filename(), MeOverride :: boolean(), TeOverride :: boolean()) -> @@ -111,7 +110,7 @@ Unload the mib specified by the `Filename` argument from the mib-server. The `MeOverride` and `TeOverride` arguments specifies how the mib-server shall handle duplicate mib- and trap- entries. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback unload_mib(State :: term(), FileName :: filename(), MeOverride :: boolean(), TeOverride :: boolean()) -> @@ -121,7 +120,7 @@ handle duplicate mib- and trap- entries. Find the mib-entry corresponding to the `Oid`. If it is a variable, the `Oid` must be .0 and if it is a table, `Oid` must be """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback lookup(State :: term(), Oid :: snmp:oid()) -> {false, Reason :: term()} | {variable, MibEntry :: snmpa:me()} | @@ -131,7 +130,7 @@ must be .0 and if it is a table, `Oid` must be -doc """ Finds the lexicographically next oid. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback next(State :: term(), Oid :: snmp:oid(), MibView :: mib_view()) -> endOfView | false | {subagent, SubAgentPid :: pid(), SAOid :: snmp:oid()} | @@ -141,7 +140,7 @@ Finds the lexicographically next oid. -doc """ Register the subagent, process, handling part of the mib-tree. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback register_subagent(State :: term(), Oid :: snmp:oid(), Pid :: pid()) -> @@ -154,7 +153,7 @@ Unregister the subagent, handling part of the mib-tree, as specified by the When unregister the subagent using an `oid()`, the `t:pid/0` of the process handling the sub-tree is also returned. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback unregister_subagent(State :: term(), PidOrOid :: pid() | snmp:oid()) -> {ok, NewState :: term()} | % When second arg was a pid() @@ -164,28 +163,28 @@ handling the sub-tree is also returned. -doc """ Dump the mib-server data to `stdio` (Destination = `io`) or the specified file. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback dump(State :: term(), Destination :: io | filename()) -> ok | {error, Reason :: term()}. -doc """ Retrieve the mib-file to which an given `oid()` belongs. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback which_mib(State :: term(), Oid :: snmp:oid()) -> {ok, Mib :: string()} | {error, Reason :: term()}. -doc """ Retrieve all loaded mib-files. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback which_mibs(State :: term()) -> [{MibName :: atom(), Filename :: filename()}]. -doc """ Retrieve the mib file for the mib. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback whereis_mib(State :: term(), MibName :: atom()) -> {ok, Filename :: filename()} | {error, Reason :: term()}. @@ -195,7 +194,7 @@ Retrieve misc info for the mib data. This is a utility function used to inspect, for instance, memory usage, in a simple way. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback info(State :: term()) -> list(). -doc """ @@ -204,7 +203,7 @@ Perform a backup of the mib-server data. Note that its implementation dependent (and also dependent on mib-storage is used) if a backup is possible. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback backup(State :: term(), BackupDir :: string()) -> ok | {error, Reason :: term()}. @@ -213,7 +212,7 @@ Perform a code-change (upgrade or downgrade). See `m:gen_server` for more info regarding the `Vsn` and `Extra` arguments. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback code_change(Direction :: up | down, Vsn :: term(), Extra :: term(), diff --git a/lib/snmp/src/agent/snmpa_mib_storage.erl b/lib/snmp/src/agent/snmpa_mib_storage.erl index 36561d3e023b..e8bf5f7dedf5 100644 --- a/lib/snmp/src/agent/snmpa_mib_storage.erl +++ b/lib/snmp/src/agent/snmpa_mib_storage.erl @@ -45,8 +45,7 @@ A `snmpa_mib_storage` compliant module must export the following functions: The semantics of them and their exact signatures are explained below. """. --moduledoc(#{since => "OTP R16B01", - titles => [{callback,<<"CALLBACK FUNCTIONS">>}]}). +-moduledoc(#{since => "OTP R16B01"}). -export_type([ mib_storage_fields/0, @@ -86,7 +85,7 @@ implementations). Note also that the `Options` argument comes from the `options` config option of the mib-storage config option, and is passed on as is. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback open(Name :: atom(), RecName :: atom(), Fields :: mib_storage_fields(), @@ -106,7 +105,7 @@ the mib-storage config option, and is passed on as is. -doc """ Close the mib-storage table. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback close(TabId :: mib_storage_table_id()) -> term(). @@ -120,7 +119,7 @@ Close the mib-storage table. -doc """ Read a record from the mib-storage table. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback read(TabId :: mib_storage_table_id(), Key :: term()) -> false | {value, Record :: tuple()}. @@ -135,7 +134,7 @@ Read a record from the mib-storage table. -doc """ Write a record to the mib-storage table. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback write(TabId :: mib_storage_table_id(), Record :: tuple()) -> ok | {error, Reason :: term()}. @@ -150,7 +149,7 @@ Write a record to the mib-storage table. -doc """ Delete an entire mib-storage table. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback delete(TabId :: mib_storage_table_id()) -> snmp:void(). @@ -164,7 +163,7 @@ Delete an entire mib-storage table. -doc """ Delete a record from the mib-storage table. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback delete(TabId :: mib_storage_table_id(), Key :: term()) -> ok | {error, Reason :: term()}. @@ -180,7 +179,7 @@ Delete a record from the mib-storage table. -doc """ Search the mib-storage table for record that match the specified pattern. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback match_object(TabId :: mib_storage_table_id(), Pattern :: ets:match_pattern()) -> Recs :: [tuple()] | {error, Reason :: term()}. @@ -198,7 +197,7 @@ Search the mib-storage table for record that match the specified pattern. Search the mib-storage table for record that match the specified pattern and then delete them. The records deleted are also returned. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback match_delete(TabId :: mib_storage_table_id(), Pattern :: ets:match_pattern()) -> Recs :: [tuple()] | {error, Reason :: term()}. @@ -213,7 +212,7 @@ then delete them. The records deleted are also returned. -doc """ Return all records in the mib-storage table in the form of a list. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback tab2list(TabId :: mib_storage_table_id()) -> [tuple()]. @@ -228,11 +227,11 @@ Return all records in the mib-storage table in the form of a list. -doc """ Retrieve implementation dependent mib-storage table information. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback info(TabId :: mib_storage_table_id()) -> Info :: term(). --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback info(TabId :: mib_storage_table_id(), Item :: atom()) -> Info :: term(). @@ -248,7 +247,7 @@ Synchronize the mib-storage table. What this means, if anything, is implementation dependent. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback sync(TabId :: mib_storage_table_id()) -> snmp:void(). @@ -264,7 +263,7 @@ Perform a backup of the mib-storage table. What this means, if anything, is implementation dependent. """. --doc(#{title => <<"CALLBACK FUNCTIONS">>,since => <<"OTP R16B01">>}). +-doc(#{since => <<"OTP R16B01">>}). -callback backup(TabId :: mib_storage_table_id(), Dir :: file:filename()) -> ok | {error, Reason :: term()}. diff --git a/lib/ssh/src/ssh.erl b/lib/ssh/src/ssh.erl index 1d69d381b52c..e2fb2eca9510 100644 --- a/lib/ssh/src/ssh.erl +++ b/lib/ssh/src/ssh.erl @@ -131,12 +131,6 @@ The directory could be changed with the option - `id_rsa` and `id_rsa.pub` - `id_ecdsa` and `id_ecdsa.pub` """. --moduledoc(#{titles => - [{type,<<"Client Options">>}, - {type,<<"Daemon Options">>}, - {type,<<"Common Options">>}, - {type,<<"Legacy Algorithms">>}, - {type,<<"Other data types">>}]}). -include("ssh.hrl"). -include("ssh_connect.hrl"). @@ -210,7 +204,7 @@ Opaque data type representing a daemon. Returned by the functions [`daemon/1,2,3`](`daemon/1`). """. --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -opaque daemon_ref() :: pid() . -doc """ Opaque data type representing a channel inside a connection. @@ -218,7 +212,7 @@ 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(#{group => <<"Other data types">>}). -opaque channel_id() :: non_neg_integer(). -doc """ Opaque data type representing a connection between a client and a server @@ -227,7 +221,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(#{group => <<"Other data types">>}). -type connection_ref() :: pid(). % should be -opaque, but that gives problems %%-------------------------------------------------------------------- @@ -429,13 +423,13 @@ close(ConnectionRef) -> %%-------------------------------------------------------------------- %% Description: Retrieves information about a connection. %%--------------------------------------------------------------------- --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -type version() :: {protocol_version(), software_version()}. --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -type protocol_version() :: {Major::pos_integer(), Minor::non_neg_integer()}. --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -type software_version() :: string(). --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -type conn_info_algs() :: [{kex, kex_alg()} | {hkey, pubkey_alg()} | {encrypt, cipher_alg()} @@ -453,10 +447,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(#{group => <<"Other data types">>}). -type conn_info_channels() :: [proplists:proplist()]. --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -type connection_info_tuple() :: {client_version, version()} | {server_version, version()} @@ -678,7 +672,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(#{group => <<"Other data types">>}). -type daemon_info_tuple() :: {port, inet:port_number()} | {ip, inet:ip_address()} diff --git a/lib/ssh/src/ssh.hrl b/lib/ssh/src/ssh.hrl index badd39575152..de0396d4340e 100644 --- a/lib/ssh/src/ssh.hrl +++ b/lib/ssh/src/ssh.hrl @@ -124,14 +124,14 @@ %% Types -type role() :: client | server . --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"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(#{group => <<"Other data types">>}). -type open_socket() :: gen_tcp:socket(). -doc """ @@ -150,19 +150,19 @@ If the subsystems option is not present, the value of default. The option can be set to the empty list if you do not want the daemon to run any subsystems. """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type subsystem_spec() :: {Name::string(), mod_args()} . --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type algs_list() :: list( alg_entry() ). --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type alg_entry() :: {kex, [kex_alg()]} | {public_key, [pubkey_alg()]} | {cipher, double_algs(cipher_alg())} | {mac, double_algs(mac_alg())} | {compression, double_algs(compression_alg())} . --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type kex_alg() :: 'diffie-hellman-group-exchange-sha256' | 'diffie-hellman-group14-sha256' | @@ -176,7 +176,7 @@ to run any subsystems. 'ecdh-sha2-nistp521' | legacy_kex_alg(). --doc(#{title => <<"Legacy Algorithms">>}). +-doc(#{group => <<"Legacy Algorithms">>}). -type legacy_kex_alg() :: %% Gone in OpenSSH 7.3.p1 'diffie-hellman-group1-sha1' | @@ -184,7 +184,7 @@ to run any subsystems. 'diffie-hellman-group14-sha1' | 'diffie-hellman-group-exchange-sha1'. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type pubkey_alg() :: 'ecdsa-sha2-nistp256' | 'ecdsa-sha2-nistp384' | @@ -195,13 +195,13 @@ to run any subsystems. 'rsa-sha2-512' | legacy_pubkey_alg(). --doc(#{title => <<"Legacy Algorithms">>}). +-doc(#{group => <<"Legacy Algorithms">>}). -type legacy_pubkey_alg() :: 'ssh-rsa' | %% Gone in OpenSSH 7.3.p1: 'ssh-dss'. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type cipher_alg() :: 'aes128-ctr' | 'aes128-gcm@openssh.com' | @@ -212,7 +212,7 @@ to run any subsystems. disabled_cipher_alg() | legacy_cipher_alg(). --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type disabled_cipher_alg() :: %% not enabled by default as it might not be compatible with %% other implemenations @@ -220,7 +220,7 @@ to run any subsystems. 'AEAD_AES_128_GCM' | 'AEAD_AES_256_GCM'. --doc(#{title => <<"Legacy Algorithms">>}). +-doc(#{group => <<"Legacy Algorithms">>}). -type legacy_cipher_alg() :: %% Gone in OpenSSH 7.6 'aes128-cbc' | @@ -228,7 +228,7 @@ to run any subsystems. 'aes256-cbc' | '3des-cbc'. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type mac_alg() :: 'hmac-sha1' | 'hmac-sha1-etm@openssh.com' | @@ -239,16 +239,16 @@ to run any subsystems. disabled_mac_alg() | legacy_mac_alg(). --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type disabled_mac_alg() :: 'AEAD_AES_128_GCM' | 'AEAD_AES_256_GCM'. --doc(#{title => <<"Legacy Algorithms">>}). +-doc(#{group => <<"Legacy Algorithms">>}). -type legacy_mac_alg() :: 'hmac-sha1-96'. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type compression_alg() :: 'none' | 'zlib' | 'zlib@openssh.com' @@ -292,7 +292,7 @@ time. > you know exactly what you are doing. If you do not understand the values then > you are not supposed to change them. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type double_algs(AlgType) :: list( {client2server,[AlgType]} | {server2client,[AlgType]} ) | [AlgType]. @@ -343,24 +343,24 @@ The example specifies that: For background and more examples see the [User's Guide](configure_algos.md#introduction). """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type modify_algs_list() :: list( {append,algs_list()} | {prepend,algs_list()} | {rm,algs_list()} ) . -type internal_options() :: ssh_options:private_options(). -type socket_options() :: [gen_tcp:connect_option() | gen_tcp:listen_option()]. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type client_options() :: [ client_option() ] . --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type daemon_options() :: [ daemon_option() ]. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type common_options() :: [ common_option() ]. -doc """ The options above can be used both in clients and in daemons (servers). They are further explained below. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type common_option() :: ssh_file:user_dir_common_option() | profile_common_option() @@ -389,7 +389,7 @@ one server that has the same `ip-address` and `port`. If this property is not explicitly set, it is assumed that the the `ip-address` and `port` uniquely identifies the SSH daemon. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type profile_common_option() :: {profile, atom() }. -doc """ Sets a time-out on a connection when no channels are open. Defaults to @@ -402,9 +402,9 @@ For more information about timeouts, see the [Timeouts section ](hardening.md#timeouts)in the User's Guide [Hardening](hardening.md) chapter. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type max_idle_time_common_option() :: {idle_time, timeout()}. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type rekey_limit_common_option() :: {rekey_limit, Bytes::limit_bytes() | {Minutes::limit_time(), Bytes::limit_bytes()} }. @@ -412,10 +412,10 @@ For more information about timeouts, see the Sets a limit for the size of a logged item excluding a header. The unit is bytes and the value defaults to 500. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type max_log_item_len_common_option() :: {max_log_item_len, limit_bytes()} . --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type limit_bytes() :: non_neg_integer() | infinity . % non_neg_integer due to compatibility -doc """ Sets the limit when rekeying is to be initiated. Both the max time and max @@ -434,7 +434,7 @@ certain amount of data has been transferred. If the option value is set to `{infinity, infinity}`, no rekeying will be initiated. Note that rekeying initiated by the peer will still be performed. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type limit_time() :: pos_integer() | infinity . -doc """ @@ -459,10 +459,10 @@ where `...` are arguments to `F` as in `m:ssh_client_key_api` and/or `m:ssh_server_key_api`. The `UserOptions` are the options given to [ssh:connect](`connect/3`), [ssh:shell](`shell/1`) or [ssh:daemon](`daemon/2`). """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type key_cb_common_option() :: {key_cb, Module::atom() | {Module::atom(),Opts::[term()]} } . -doc "Provides a fun to implement your own logging or other handling at disconnects.". --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type disconnectfun_common_option() :: {disconnectfun, fun((Reason::term()) -> void | any()) }. -doc """ @@ -470,7 +470,7 @@ Provides a fun to implement your own logging or other action when an unexpected message arrives. If the fun returns `report` the usual info report is issued but if `skip` is returned no report is generated. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type unexpectedfun_common_option() :: {unexpectedfun, fun((Message::term(),{Host::term(),Port::term()}) -> report | skip ) }. -doc """ @@ -484,7 +484,7 @@ The default behaviour is ignore the message. To get a printout for each message with `AlwaysDisplay = true`, use for example `{ssh_msg_debug_fun, fun(_,true,M,_)-> io:format("DEBUG: ~p~n", [M]) end}` """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type ssh_msg_debug_fun_common_option() :: {ssh_msg_debug_fun, fun((ssh:connection_ref(),AlwaysDisplay::boolean(),Msg::binary(),LanguageTag::binary()) -> any()) } . @@ -499,7 +499,7 @@ the ssh software brand and version. The value `{random, Nmin, Nmax}` will make a random string with at least `Nmin` characters and at most `Nmax` characters. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type id_string_common_option() :: {id_string, string() | random | {random,Nmin::pos_integer(),Nmax::pos_integer()} }. -doc """ List of user (client) public key algorithms to try to use. @@ -514,11 +514,11 @@ and current user's public keys. See also the option [`user_dir`](`t:ssh_file:user_dir_common_option/0`) for specifying the path to the user's keys. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type pref_public_key_algs_common_option() :: {pref_public_key_algs, [pubkey_alg()] } . --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type preferred_algorithms_common_option():: {preferred_algorithms, algs_list()}. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type modify_algorithms_common_option() :: {modify_algorithms, modify_algs_list()}. -doc """ Comma-separated string that determines which authentication methods that the @@ -527,17 +527,17 @@ client shall support and in which order they are tried. Defaults to Note that the client is free to use any order and to exclude methods. """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type auth_methods_common_option() :: {auth_methods, string() }. -doc "IP version to use when the host address is specified as `any`.". --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type inet_common_option() :: {inet, inet | inet6} . -doc """ Allows an existing file-descriptor to be used (passed on to the transport protocol). """. --doc(#{title => <<"Common Options">>}). +-doc(#{group => <<"Common Options">>}). -type fd_common_option() :: {fd, gen_tcp:socket()} . @@ -545,7 +545,7 @@ protocol). Opaque types that define experimental options that are not to be used in products. """. --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -type opaque_common_options() :: {transport, {atom(),atom(),atom()} } | {vsn, {non_neg_integer(),non_neg_integer()} } @@ -566,7 +566,7 @@ Also note that setting a `t:gen_tcp:connect_option/0` could change the socket in a way that impacts the ssh client's behaviour negatively. You use it on your own risk. """. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type client_option() :: ssh_file:pubkey_passphrase_client_options() | host_accepting_client_options() @@ -578,7 +578,7 @@ risk. | gen_tcp:connect_option() | ?COMMON_OPTION . --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -type opaque_client_options() :: {keyboard_interact_fun, fun((Name::iodata(), Instruction::iodata(), @@ -647,27 +647,27 @@ risk. Defaults to `false` """. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type host_accepting_client_options() :: {silently_accept_hosts, accept_hosts()} | {user_interaction, boolean()} | {save_accepted_host, boolean()} | {quiet_mode, boolean()} . --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type accept_hosts() :: boolean() | accept_callback() | {HashAlgoSpec::fp_digest_alg(), accept_callback()}. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type fp_digest_alg() :: 'md5' | crypto:sha1() | crypto:sha2() . --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type accept_callback() :: fun((PeerName::string(), fingerprint() ) -> boolean()) % Old style | fun((PeerName::string(), Port::inet:port_number(), fingerprint() ) -> boolean()) % New style . --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type fingerprint() :: string() | [string()]. -doc """ @@ -678,7 +678,7 @@ risk. option is not given, the user is asked for a password, if the password authentication method is attempted. """. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type authentication_client_options() :: {user, string()} | {password, string()} . @@ -689,7 +689,7 @@ connected server in choosing a group. See [RFC 4419](https://tools.ietf.org/html/rfc4419) for the details. The default value is `{1024, 6144, 8192}`. """. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type diffie_hellman_group_exchange_client_option() :: {dh_gex_limits, {Min::pos_integer(), I::pos_integer(), Max::pos_integer()} } . @@ -700,7 +700,7 @@ in milli-seconds and the default value is `infinity`. See the parameter `Timeout` in `connect/4` for a timeout of the negotiation phase. """. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type connect_timeout_client_option() :: {connect_timeout, timeout()} . -doc """ @@ -713,7 +713,7 @@ extensions. Default value is `true` which is compatible with other implementations not supporting ext-info. """. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -type recv_ext_info_client_option() :: {recv_ext_info, boolean()} . @@ -729,7 +729,7 @@ Also note that setting a `t:gen_tcp:listen_option/0` could change the socket in a way that impacts the ssh deamon's behaviour negatively. You use it on your own risk. """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type daemon_option() :: subsystem_daemon_option() | shell_daemon_option() @@ -749,20 +749,20 @@ risk. | gen_tcp:listen_option() | ?COMMON_OPTION . --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type subsystem_daemon_option() :: {subsystems, subsystem_specs()}. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type subsystem_specs() :: [ subsystem_spec() ]. --doc(#{title => <<"Daemon Options">>, +-doc(#{group => <<"Daemon Options">>, equiv => 'shell_fun/2'/0}). -type shell_daemon_option() :: {shell, shell_spec()} . --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type shell_spec() :: mod_fun_args() | shell_fun() | disabled . --doc(#{title => <<"Daemon Options">>, +-doc(#{group => <<"Daemon Options">>, equiv => 'shell_fun/2'/0}). -type shell_fun() :: 'shell_fun/1'() | 'shell_fun/2'() . --doc(#{title => <<"Daemon Options">>, +-doc(#{group => <<"Daemon Options">>, equiv => 'shell_fun/2'/0}). -type 'shell_fun/1'() :: fun((User::string()) -> pid()) . -doc """ @@ -773,20 +773,20 @@ See the option [`exec-option`](`t:exec_daemon_option/0`) for a description of how the daemon executes shell-requests and exec-requests depending on the shell- and exec-options. """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type 'shell_fun/2'() :: fun((User::string(), PeerAddr::inet:ip_address()) -> pid()). --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type exec_daemon_option() :: {exec, exec_spec()} . --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type exec_spec() :: {direct, exec_fun()} | disabled | deprecated_exec_opt(). --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type exec_fun() :: 'exec_fun/1'() | 'exec_fun/2'() | 'exec_fun/3'(). --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type 'exec_fun/1'() :: fun((Cmd::string()) -> exec_result()) . --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type 'exec_fun/2'() :: fun((Cmd::string(), User::string()) -> exec_result()) . --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type 'exec_fun/3'() :: fun((Cmd::string(), User::string(), ClientAddr::ip_port()) -> exec_result()) . -doc """ This option changes how the daemon executes exec-requests from clients. The term @@ -858,13 +858,13 @@ implied by the custom CLI. > retained but obey the rules 1-6 above if conflicting. The old and undocumented > style should not be used in new programs. """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type exec_result() :: {ok,Result::term()} | {error,Reason::term()} . -doc """ Old-style exec specification that are kept for compatibility, but should not be used in new programs """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type deprecated_exec_opt() :: fun() | mod_fun_args() . -doc """ @@ -877,20 +877,20 @@ own CLI channel. If `ssh_cli` is set to `no_cli`, the CLI channels like [`shell`](`t:shell_daemon_option/0`) and [`exec`](`t:exec_daemon_option/0`) are disabled and only subsystem channels are allowed. """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type ssh_cli_daemon_option() :: {ssh_cli, mod_args() | no_cli }. -doc """ Enables (`true`) or disables (`false`) the possibility to tunnel a TCP/IP connection out of a [server](`daemon/2`). Disabled per default. """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type tcpip_tunnel_out_daemon_option() :: {tcpip_tunnel_out, boolean()} . -doc """ Enables (`true`) or disables (`false`) the possibility to tunnel a TCP/IP connection in to a [server](`daemon/2`). Disabled per default. """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type tcpip_tunnel_in_daemon_option() :: {tcpip_tunnel_in, boolean()} . -doc """ @@ -903,10 +903,10 @@ extensions. Default value is `true` which is compatible with other implementations not supporting ext-info. """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type send_ext_info_daemon_option() :: {send_ext_info, boolean()} . --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type authentication_daemon_options() :: ssh_file:system_dir_daemon_option() | {auth_method_kb_interactive_data, prompt_texts() } @@ -916,20 +916,20 @@ supporting ext-info. | {pwdfun, pwdfun_2() | pwdfun_4()} | {no_auth_needed, boolean()}. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type prompt_texts() :: kb_int_tuple() | kb_int_fun_3() | kb_int_fun_4(). --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type kb_int_fun_3() :: fun((Peer::ip_port(), User::string(), Service::string()) -> kb_int_tuple()). --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type kb_int_fun_4() :: fun((Peer::ip_port(), User::string(), Service::string(), State::any()) -> kb_int_tuple()). --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type kb_int_tuple() :: {Name::string(), Instruction::string(), Prompt::string(), Echo::boolean()}. --doc(#{title => <<"Daemon Options">>, +-doc(#{group => <<"Daemon Options">>, equiv => pwdfun_4/0}). -type pwdfun_2() :: fun((User::string(), Password::string()|pubkey) -> boolean()) . -doc """ @@ -1029,7 +1029,7 @@ supporting ext-info. The default value is `false`. """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type pwdfun_4() :: fun((User::string(), Password::string()|pubkey, PeerAddress::ip_port(), @@ -1037,14 +1037,14 @@ supporting ext-info. boolean() | disconnect | {boolean(),NewState::any()} ) . --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type diffie_hellman_group_exchange_daemon_option() :: {dh_gex_groups, [explicit_group()] | explicit_group_file() | ssh_moduli_file()} | {dh_gex_limits, {Min::pos_integer(), Max::pos_integer()} } . --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type explicit_group() :: {Size::pos_integer(),G::pos_integer(),P::pos_integer()} . --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type explicit_group_file() :: {file,string()} . -doc """ - **`dh_gex_groups`** - Defines the groups the server may choose among when @@ -1079,7 +1079,7 @@ supporting ext-info. See [RFC 4419](https://tools.ietf.org/html/rfc4419) for the function of the Max and Min values. """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type ssh_moduli_file() :: {ssh_moduli_file,string()}. -doc """ @@ -1090,7 +1090,7 @@ For more information about timeouts, see the [Timeouts section ](hardening.md#timeouts)in the User's Guide [Hardening](hardening.md) chapter. """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type max_initial_idle_time_daemon_option() :: {max_initial_idle_time, timeout()} . -doc """ Maximum time in milliseconds for the authentication negotiation. Defaults to @@ -1101,7 +1101,7 @@ For more information about timeouts, see the [Timeouts section ](hardening.md#timeouts)in the User's Guide [Hardening](hardening.md) chapter. """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type negotiation_timeout_daemon_option() :: {negotiation_timeout, timeout()} . -doc """ Maximum time in milliseconds for the first part of the ssh session setup, the @@ -1112,7 +1112,7 @@ For more information about timeouts, see the [Timeouts section ](hardening.md#timeouts)in the User's Guide [Hardening](hardening.md) chapter. """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type hello_timeout_daemon_option() :: {hello_timeout, timeout()} . -doc """ @@ -1161,7 +1161,7 @@ in the User's Guide chapter. maximum packet size that the daemon will accept in channel open requests from the client. The default value is 0. """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type hardening_daemon_options() :: {max_sessions, pos_integer()} | {max_channels, pos_integer()} @@ -1175,22 +1175,22 @@ in the User's Guide chapter. - **`failfun`** - Provides a fun to implement your own logging when a user fails to authenticate. """. --doc(#{title => <<"Daemon Options">>}). +-doc(#{group => <<"Daemon Options">>}). -type callbacks_daemon_options() :: {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(#{group => <<"Other data types">>}). -type opaque_daemon_options() :: {infofun, fun()} | opaque_common_options(). --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -type ip_port() :: {inet:ip_address(), inet:port_number()} . --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -type mod_args() :: {Module::atom(), Args::list()} . --doc(#{title => <<"Other data types">>}). +-doc(#{group => <<"Other data types">>}). -type mod_fun_args() :: {Module::atom(), Function::atom(), Args::list()} . diff --git a/lib/ssh/src/ssh_agent.erl b/lib/ssh/src/ssh_agent.erl index 5b1d0a00d7c0..dc0ada813bc7 100644 --- a/lib/ssh/src/ssh_agent.erl +++ b/lib/ssh/src/ssh_agent.erl @@ -56,9 +56,7 @@ option can be set. > The functions are _Callbacks_ for the SSH app. They are not intended to be > called from the user's code\! """. --moduledoc(#{since => "OTP 23.0", - titles => - [{type,<<"Options">>}]}). +-moduledoc(#{since => "OTP 23.0"}). -behaviour(ssh_client_key_api). @@ -72,19 +70,19 @@ option can be set. Sets the [socket path](`m:ssh_agent#SOCKET_PATH`) for the communication with the agent. """. --doc(#{title => <<"Options">>}). +-doc(#{group => <<"Options">>}). -type socket_path_option() :: {socket_path, string()}. -doc """ Sets the time-out in milliseconds when communicating with the agent via the socket. The default value is `1000`. """. --doc(#{title => <<"Options">>}). +-doc(#{group => <<"Options">>}). -type timeout_option() :: {timeout, integer()}. -doc """ The module which the `add_host_key` and `is_host_key` callbacks are delegated to. Defaults to the `m:ssh_file` module. """. --doc(#{title => <<"Options">>}). +-doc(#{group => <<"Options">>}). -type call_ssh_file_option() :: {call_ssh_file, atom()}. %% ssh_client_key_api implementation diff --git a/lib/ssh/src/ssh_connection.erl b/lib/ssh/src/ssh_connection.erl index 73b626cc9143..f062dab83bf0 100644 --- a/lib/ssh/src/ssh_connection.erl +++ b/lib/ssh/src/ssh_connection.erl @@ -42,16 +42,6 @@ If the `m:ssh_client_channel` behavior is used to implement the channel process, these messages are handled by [handle_ssh_msg/2](`c:ssh_client_channel:handle_ssh_msg/2`). """. --moduledoc(#{titles => - [{type,<<"General">>}, - {type,<<"Data Transfer">>}, - {type,<<"Closing a Channel">>}, - {type,<<"Pseudo-Terminal">>}, - {type,<<"Environment Variable">>}, - {type,<<"Shell or Command">>}, - {type,<<"Window Change">>}, - {type,<<"Signals">>}, - {type,<<"Exit Status">>}]}). -include("ssh.hrl"). -include("ssh_connect.hrl"). @@ -150,7 +140,7 @@ The valid values are `0` ("normal") and `1` ("stderr"), see exec_ch_msg/0 ]). --doc(#{title => <<"General">>}). +-doc(#{group => <<"General">>}). -type event() :: {ssh_cm, ssh:connection_ref(), channel_msg()}. -doc """ As mentioned in the introduction, the @@ -159,7 +149,7 @@ handled as messages. When writing a channel handling process without using the support by the `m:ssh_client_channel` behavior the process must handle thoose messages. """. --doc(#{title => <<"General">>}). +-doc(#{group => <<"General">>}). -type channel_msg() :: data_ch_msg() | eof_ch_msg() | closed_ch_msg() @@ -178,14 +168,14 @@ Messages that include a `WantReply` expect the channel handling process to call [ssh_connection:reply_request/4](`reply_request/4`) with the boolean value of `WantReply` as the second argument. """. --doc(#{title => <<"General">>}). +-doc(#{group => <<"General">>}). -type want_reply() :: boolean(). -doc """ Data has arrived on the channel. This event is sent as a result of calling [ssh_connection:send/3,4,5](`send/3`). """. --doc(#{title => <<"Data Transfer">>, +-doc(#{group => <<"Data Transfer">>, rfc => ~"RFC 4254, section 5.2"}). -type data_ch_msg() :: {data, ssh:channel_id(), @@ -196,7 +186,7 @@ Data has arrived on the channel. This event is sent as a result of calling Indicates that the other side sends no more data. This event is sent as a result of calling [ssh_connection:send_eof/2](`send_eof/2`). """. --doc(#{title => <<"Closing a Channel">>, +-doc(#{group => <<"Closing a Channel">>, rfc => ~"RFC 4254, section 5.3"}). -type eof_ch_msg() :: {eof, ssh:channel_id() @@ -208,7 +198,7 @@ this message. There is currently no function to generate this event as the signals referred to are on OS-level and not something generated by an Erlang program. """. --doc(#{title => <<"Signals">>, +-doc(#{group => <<"Signals">>, rfc => ~"RFC 4254, section 6.9"}). -type signal_ch_msg() :: {signal, ssh:channel_id(), @@ -220,7 +210,7 @@ message can be received. For details on valid string values, see [RFC 4254](https://tools.ietf.org/html/rfc4254#section-6.10) Section 6.10, which shows a special case of these signals. """. --doc(#{title => <<"Exit Status">>, +-doc(#{group => <<"Exit Status">>, rfc => ~"RFC 4254, section 6.10"}). -type exit_signal_ch_msg() :: {exit_signal, ssh:channel_id(), ExitSignal :: string(), @@ -232,7 +222,7 @@ be sent to return the exit status of the command. A zero `exit_status` usually means that the command terminated successfully. This event is sent as a result of calling [ssh_connection:exit_status/3](`exit_status/3`). """. --doc(#{title => <<"Exit Status">>, +-doc(#{group => <<"Exit Status">>, rfc => ~"RFC 4254, section 6.10"}). -type exit_status_ch_msg() :: {exit_status, ssh:channel_id(), @@ -243,7 +233,7 @@ This event is sent as a result of calling [ssh_connection:close/2](`close/2`). Both the handling of this event and sending it are taken care of by the `m:ssh_client_channel` behavior. """. --doc(#{title => <<"Closing a Channel">>, +-doc(#{group => <<"Closing a Channel">>, rfc => ~"RFC 4254, section 5.3"}). -type closed_ch_msg() :: {closed, ssh:channel_id() @@ -252,7 +242,7 @@ Both the handling of this event and sending it are taken care of by the Environment variables can be passed to the shell/command to be started later. This event is sent as a result of calling [ssh_connection:setenv/5](`setenv/5`). """. --doc(#{title => <<"Environment Variable">>, +-doc(#{group => <<"Environment Variable">>, rfc => ~"RFC 4254, section 6.4"}). -type env_ch_msg() :: {env, ssh:channel_id(), @@ -260,7 +250,7 @@ This event is sent as a result of calling [ssh_connection:setenv/5](`setenv/5`). Var :: string(), Value :: string() } . --doc(#{title => <<"Pseudo-Terminal">>, +-doc(#{group => <<"Pseudo-Terminal">>, rfc => ~"RFC 4254, section 6.2"}). -type pty_ch_msg() :: {pty, ssh:channel_id(), @@ -286,7 +276,7 @@ also be an `Opcode` if the mnemonic name is not listed in the RFC. Example: `OP code: 53, mnemonic name ECHO erlang atom: echo`. This event is sent as a result of calling [ssh_connection:ptty_alloc/4](`ptty_alloc/4`). """. --doc(#{title => <<"Pseudo-Terminal">>, +-doc(#{group => <<"Pseudo-Terminal">>, rfc => ~"RFC 4254, section 6.2"}). -type term_mode() :: {Opcode :: atom() | byte(), Value :: non_neg_integer()} . @@ -295,7 +285,7 @@ result of calling [ssh_connection:ptty_alloc/4](`ptty_alloc/4`). This message requests that the user default shell is started at the other end. This event is sent as a result of calling [ssh_connection:shell/2](`shell/2`). """. --doc(#{title => <<"Shell or Command">>, +-doc(#{group => <<"Shell or Command">>, rfc => ~"RFC 4254, section 6.5"}). -type shell_ch_msg() :: {shell, ssh:channel_id(), @@ -306,7 +296,7 @@ When the window (terminal) size changes on the client side, it _can_ send a message to the server side to inform it of the new dimensions. No API function generates this event. """. --doc(#{title => <<"Window Change">>, +-doc(#{group => <<"Window Change">>, rfc => ~"RFC 4254, section 6.7"}). -type window_change_ch_msg() :: {window_change, ssh:channel_id(), @@ -319,7 +309,7 @@ generates this event. This message requests that the server starts execution of the given command. This event is sent as a result of calling [ssh_connection:exec/4 ](`exec/4`). """. --doc(#{title => <<"Shell or Command">>, +-doc(#{group => <<"Shell or Command">>, rfc => ~"RFC 4254, section 6.5"}). -type exec_ch_msg() :: {exec, ssh:channel_id(), diff --git a/lib/ssh/src/ssh_file.erl b/lib/ssh/src/ssh_file.erl index 582058e988d2..76b6f059dc92 100644 --- a/lib/ssh/src/ssh_file.erl +++ b/lib/ssh/src/ssh_file.erl @@ -168,9 +168,7 @@ Clients uses all files stored in the [USERDIR](`m:ssh_file#USERDIR`) directory. To change the USERDIR, see the [user_dir](`t:user_dir_common_option/0`) option """. --moduledoc(#{since => "OTP 21.2", - titles => - [{type,<<"Options">>}]}). +-moduledoc(#{since => "OTP 21.2"}). -include_lib("public_key/include/public_key.hrl"). -include_lib("kernel/include/file.hrl"). @@ -186,7 +184,7 @@ Clients uses all files stored in the [USERDIR](`m:ssh_file#USERDIR`) directory. -export([host_key/2, is_auth_key/3]). -export_type([system_dir_daemon_option/0]). -doc "Sets the [system directory](`m:ssh_file#SYSDIR`).". --doc(#{title => <<"Options">>}). +-doc(#{group => <<"Options">>}). -type system_dir_daemon_option() :: {system_dir, string()}. %%%--------------------- client exports --------------------------- @@ -199,7 +197,7 @@ supplied with thoose options. Note that EdDSA passhrases (Curves 25519 and 448) are not implemented. """. --doc(#{title => <<"Options">>}). +-doc(#{group => <<"Options">>}). -type pubkey_passphrase_client_options() :: {dsa_pass_phrase, string()} | {rsa_pass_phrase, string()} %% Not yet implemented: | {ed25519_pass_phrase, string()} @@ -218,15 +216,15 @@ Note that EdDSA passhrases (Curves 25519 and 448) are not implemented. ]). -doc "Sets the [user directory](`m:ssh_file#USERDIR`).". --doc(#{title => <<"Options">>}). +-doc(#{group => <<"Options">>}). -type user_dir_common_option() :: {user_dir, string()}. --doc(#{title => <<"Options">>}). +-doc(#{group => <<"Options">>}). -type user_dir_fun_common_option() :: {user_dir_fun, user2dir()}. -doc """ Sets the [user directory](`m:ssh_file#USERDIR`) dynamically by evaluating the `user2dir` function. """. --doc(#{title => <<"Options">>}). +-doc(#{group => <<"Options">>}). -type user2dir() :: fun((RemoteUserName::string()) -> UserDir :: string()) . -doc """ @@ -238,16 +236,16 @@ To set it, set the option `{key_cb, {ssh_file, [{optimize,TimeOrSpace}]}` in the call of ["ssh:connect/3](`ssh:connect/3`), `ssh:daemon/2` or similar function call that initiates an ssh connection. """. --doc(#{title => <<"Options">>}). +-doc(#{group => <<"Options">>}). -type optimize_key_lookup() :: {optimize, time|space} . -doc "The key representation". --doc(#{title => <<"Options">>}). +-doc(#{group => <<"Options">>}). -type key() :: public_key:public_key() | public_key:private_key() . --doc(#{title => <<"Options">>}). +-doc(#{group => <<"Options">>}). -type experimental_openssh_key_v1() :: [{key(), openssh_key_v1_attributes()}]. -doc "Types for the experimental implementaition of the `openssh_key_v1` format.". --doc(#{title => <<"Options">>}). +-doc(#{group => <<"Options">>}). -type openssh_key_v1_attributes() :: [{atom(),term()}]. %%%================================================================ diff --git a/lib/ssh/src/ssh_sftp.erl b/lib/ssh/src/ssh_sftp.erl index 1e9367f90915..5fc13c2f6a35 100644 --- a/lib/ssh/src/ssh_sftp.erl +++ b/lib/ssh/src/ssh_sftp.erl @@ -29,8 +29,6 @@ SFTP client. This module implements an SSH FTP (SFTP) client. SFTP is a secure, encrypted file transfer service available for SSH. """. --moduledoc(#{titles => - [{type,<<"Crypto open_tar">>}]}). -behaviour(ssh_client_channel). @@ -309,10 +307,10 @@ open(Pid, File, Mode, FileOpTimeout) -> call(Pid, {open, false, File, Mode}, FileOpTimeout). --doc(#{title => <<"Crypto open_tar">>}). +-doc(#{group => <<"Crypto open_tar">>}). -type tar_crypto_spec() :: encrypt_spec() | decrypt_spec() . --doc(#{title => <<"Crypto open_tar">>}). +-doc(#{group => <<"Crypto open_tar">>}). -type encrypt_spec() :: {init_fun(), crypto_fun(), final_fun()} . -doc """ Specifies the encryption or decryption applied to tar files when using @@ -325,14 +323,14 @@ For code examples see Section [Example with encryption](using_ssh.md#example-with-encryption) in the ssh Users Guide. """. --doc(#{title => <<"Crypto open_tar">>}). +-doc(#{group => <<"Crypto open_tar">>}). -type decrypt_spec() :: {init_fun(), crypto_fun()} . --doc(#{title => <<"Crypto open_tar">>}). +-doc(#{group => <<"Crypto open_tar">>}). -type init_fun() :: fun(() -> {ok,crypto_state()}) | fun(() -> {ok,crypto_state(),chunk_size()}) . --doc(#{title => <<"Crypto open_tar">>}). +-doc(#{group => <<"Crypto open_tar">>}). -type crypto_fun() :: fun((TextIn::binary(), crypto_state()) -> crypto_result()) . -doc """ The initial `t:crypto_state/0` returned from the `t:init_fun/0` is folded into @@ -344,7 +342,7 @@ next call of the `t:crypto_fun/0`. If the `t:crypto_fun/0` reurns a `t:chunk_size/0`, that value is as block size for further blocks in calls to `t:crypto_fun/0`. """. --doc(#{title => <<"Crypto open_tar">>}). +-doc(#{group => <<"Crypto open_tar">>}). -type crypto_result() :: {ok,TextOut::binary(),crypto_state()} | {ok,TextOut::binary(),crypto_state(),chunk_size()} . @@ -354,10 +352,10 @@ If doing encryption, the `t:final_fun/0` in the The `t:final_fun/0` is responsible for padding (if needed) and encryption of that last piece. """. --doc(#{title => <<"Crypto open_tar">>}). +-doc(#{group => <<"Crypto open_tar">>}). -type final_fun() :: fun((FinalTextIn::binary(),crypto_state()) -> {ok,FinalTextOut::binary()}) . --doc(#{title => <<"Crypto open_tar">>}). +-doc(#{group => <<"Crypto open_tar">>}). -type chunk_size() :: undefined | pos_integer(). -doc """ The `t:init_fun/0` in the [tar_crypto_spec](`t:tar_crypto_spec/0`) is applied @@ -374,7 +372,7 @@ stream crypto, whereas a fixed `t:chunk_size/0` is intended for block crypto. A `t:chunk_size/0` can be changed in the return from the `t:crypto_fun/0`. The value can be changed between `t:pos_integer/0` and `undefined`. """. --doc(#{title => <<"Crypto open_tar">>}). +-doc(#{group => <<"Crypto open_tar">>}). -type crypto_state() :: any() . diff --git a/lib/ssl/src/ssl.erl b/lib/ssl/src/ssl.erl index c68ee105c77e..ff12e844b5c7 100644 --- a/lib/ssl/src/ssl.erl +++ b/lib/ssl/src/ssl.erl @@ -47,24 +47,6 @@ Special Erlang node configuration for the application can be found in [SSL Application](ssl_app.md). """. --moduledoc(#{titles => - [{type,<<"Socket">>}, - {type,<<"Algorithms">>}, - {type,<<"Certificates">>}, - {type,<<"Algorithms Legacy">>}, - {type,<<"Client Options">>}, - {type,<<"Server Options">>}, - {type,<<"Client and Server Options">>}, - {type,<<"Info">>}, - {type,<<"Deprecated">>}, - {function,<<"Client API">>}, - {function,<<"Server API">>}, - {function,<<"Client and Server API">>}, - {function,<<"TLS-1.3 Only API">>}, - {function,<<"Pre TLS-1.3 API">>}, - {function,<<"Utility Functions">>}, - {function,<<"Deprecated API">>} - ]}). -include_lib("public_key/include/public_key.hrl"). -include_lib("kernel/include/logger.hrl"). @@ -201,7 +183,7 @@ Special Erlang node configuration for the application can be found in %% ------------------------------------------------------------------------------------------------------- --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ A socket that can be used to perform a so-called "START-TLS", which means using an already connected socket previously used for plain TCP @@ -211,7 +193,7 @@ Both sides needs to agree on the upgrade. """. -type socket() :: gen_tcp:socket() | socket:socket(). % exported --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ Options for the transport socket. @@ -224,7 +206,7 @@ only relevant for TLS and not DTLS. """. -type socket_option() :: gen_tcp:connect_option() | gen_tcp:listen_option() | gen_udp:option(). % exported --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ An opaque reference to the TLS/DTLS connection. @@ -233,25 +215,25 @@ Note that despite being opaque, matching `sslsocket()` instances is allowed. -type sslsocket() :: any(). % exported --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ An option related to the TLS/DTLS protocol. """. -type tls_option() :: tls_client_option() | tls_server_option(). % exported --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ An option that can be supplied to a TLS client. """. -type tls_client_option() :: client_option() | common_option() | socket_option() | transport_option(). % exported --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ An option that can be supplied to a TLS server. """. -type tls_server_option() :: server_option() | common_option() | socket_option() | transport_option(). % exported --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ The type for the messages that are delivered to the owner of a TLS/DTLS socket in active mode. @@ -269,7 +251,7 @@ to passive (`{active, false}`) mode. -type active_msgs() :: {ssl, sslsocket(), Data::binary() | list()} | {ssl_closed, sslsocket()} | {ssl_error, sslsocket(), Alert::error_alert() | Reason::any()} | {ssl_passive, sslsocket()}. % exported --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ Transport option defines a callback module and message tags to handle the underlying transport socket. @@ -294,13 +276,13 @@ directly. For DTLS this feature is considered experimental. ClosedTag::atom(), ErrTag::atom()}} | {cb_info, {CallbackModule::atom(), DataTag::atom(), ClosedTag::atom(), ErrTag::atom(), PassiveTag::atom()}}. --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ A name or address to a host. """. -type host() :: inet:hostname() | inet:ip_address(). % exported --doc(#{title => +-doc(#{group => <<"Socket">>}). -doc """ Identifies a TLS session prior to TLS-1.3. @@ -308,37 +290,37 @@ Identifies a TLS session prior to TLS-1.3. -type session_id() :: binary(). % exported --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ TLS or DTLS protocol version. """. -type protocol_version() :: tls_version() | dtls_version(). % exported --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ TLS protocol version. """. -type tls_version() :: 'tlsv1.2' | 'tlsv1.3' | tls_legacy_version(). --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ DTLS protocol version. """. -type dtls_version() :: 'dtlsv1.2' | dtls_legacy_version(). --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ A TLS protocol version that are no longer supported by default for security reasons. """. -type tls_legacy_version() :: tlsv1 | 'tlsv1.1' . --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ A DTLS protocol version that are no longer supported by default for security reasons. """. -type dtls_legacy_version() :: 'dtlsv1'. --doc(#{title => <<"Algorithms">>}). +-doc(#{group => <<"Algorithms">>}). -doc """ Cipher algorithms that can be used for payload encryption. """. @@ -352,7 +334,7 @@ Cipher algorithms that can be used for payload encryption. | aes_128_cbc | aes_256_cbc | legacy_cipher(). % exported --doc(#{title => <<"Algorithms Legacy">>}). +-doc(#{group => <<"Algorithms Legacy">>}). -doc """ Cipher algorithms that are no longer supported by default for security reasons. """. @@ -360,14 +342,14 @@ Cipher algorithms that are no longer supported by default for security reasons. | des_cbc | rc4_128. --doc(#{title => <<"Algorithms">>}). +-doc(#{group => <<"Algorithms">>}). -doc """ Hash algorithms used together with signing and encryption functions. """. -type hash() :: sha2() | legacy_hash(). % exported --doc(#{title => <<"Algorithms">>}). +-doc(#{group => <<"Algorithms">>}). -doc """ SHA2 hash algorithms. """. @@ -375,7 +357,7 @@ SHA2 hash algorithms. | sha384 | sha256. --doc(#{title => <<"Algorithms Legacy">>}). +-doc(#{group => <<"Algorithms Legacy">>}). -doc """ Hash algorithms that are no longer supported by default for security reasons. """. @@ -383,7 +365,7 @@ Hash algorithms that are no longer supported by default for security reasons. | sha | md5. --doc(#{title => <<"Algorithms">>}). +-doc(#{group => <<"Algorithms">>}). -doc """ Signature algorithms. """. @@ -392,13 +374,13 @@ Signature algorithms. | rsa | legacy_sign_algo(). % exported --doc(#{title => <<"Algorithms Legacy">>}). +-doc(#{group => <<"Algorithms Legacy">>}). -doc """ Signature algorithms that are no longer supported by default for security reasons. """. -type legacy_sign_algo() :: dsa. --doc(#{title => <<"Algorithms">>}). +-doc(#{group => <<"Algorithms">>}). -doc """ Signature schemes, defined by TLS-1.3, and replacing signature algorithms from TLS-1.2. @@ -443,7 +425,7 @@ still disallow sha1 use in the TLS protocol, since 27.0.1 and 26.2.5.2. | legacy_sign_scheme() . % exported --doc(#{title => <<"Algorithms">>}). +-doc(#{group => <<"Algorithms">>}). -doc """ Supported in TLS-1.3 and TLS-1.2. """. @@ -454,7 +436,7 @@ Supported in TLS-1.3 and TLS-1.2. | rsa_pss_pss_sha384 | rsa_pss_pss_sha256. --doc(#{title => <<"Algorithms Legacy">>}). +-doc(#{group => <<"Algorithms Legacy">>}). -doc """ This is only used for certificate signatures if TLS-1.2 is negotiated, meaning that the peer only supports TLS-1.2, but we also support @@ -467,7 +449,7 @@ TLS-1.3. | ecdsa_sha1 | rsa_pkcs1_sha1. --doc(#{title => <<"Algorithms">>}). +-doc(#{group => <<"Algorithms">>}). -doc """ Cipher Suite Key Exchange Algorithm will be `any` in TLS-1.3 as key exchange is no longer part of cipher suite @@ -490,7 +472,7 @@ configuration in TLS-1.3. | any. %% TLS 1.3 (any of TLS-1.3 keyexchanges) , exported --doc(#{title => <<"Algorithms">>}). +-doc(#{group => <<"Algorithms">>}). -doc """ Erlang cipher suite representation @@ -507,7 +489,7 @@ exists more reliable cipher suites that can be used instead. prf := hash() | default_prf %% Old cipher suites, version dependent }. --doc(#{title => <<"Algorithms Legacy">>}). +-doc(#{group => <<"Algorithms Legacy">>}). -doc """ For backwards compatibility only; do not use. """. @@ -515,7 +497,7 @@ For backwards compatibility only; do not use. %% TLS 1.2, internally PRE TLS 1.2 will use default_prf | {kex_algo(), cipher(), hash() | aead, hash()}. --doc(#{title => <<"Algorithms">>}). +-doc(#{group => <<"Algorithms">>}). -doc """ Key exchange configuration prior to TLS-1.3. """. @@ -529,7 +511,7 @@ Key exchange configuration prior to TLS-1.3. | secp256r1 | legacy_named_curve(). % exported --doc(#{title => <<"Algorithms Legacy">>}). +-doc(#{group => <<"Algorithms Legacy">>}). -doc """ Key exchange configuration prior to TLS-1.3. @@ -558,7 +540,7 @@ These curves have been deprecated by RFC 8422. | secp160r1 | secp160r2. --doc(#{title => <<"Algorithms">>}). +-doc(#{group => <<"Algorithms">>}). -doc """ TLS-1.3 key exchange configuration. """. @@ -573,7 +555,7 @@ TLS-1.3 key exchange configuration. | ffdhe6144 | ffdhe8192. % exported --doc(#{title => <<"Algorithms">>}). +-doc(#{group => <<"Algorithms">>}). -doc """ SRP cipher suite configuration prior to TLS-1.3. """. @@ -585,7 +567,7 @@ SRP cipher suite configuration prior to TLS-1.3. | srp_1536 | srp_1024. % exported --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ If a TLS connection fails a TLS protocol ALERT will be sent/received. @@ -594,7 +576,7 @@ with some further details will be returned. """. -type error_alert() :: {tls_alert, {tls_alert(), Description::string()}}. % exported --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ TLS Alert Protocol reasons. """. @@ -629,7 +611,7 @@ TLS Alert Protocol reasons. no_application_protocol. % exported --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ Error reason for debug purposes. @@ -639,7 +621,7 @@ Not to be matched. %% ------------------------------------------------------------------------------------------------------- --doc(#{title => +-doc(#{group => <<"Client and Server Options">>}). -doc """ Options common to both client and server side. @@ -708,7 +690,7 @@ Options common to both client and server side. {sender_spawn_opts, SpawnOpts::[erlang:spawn_opt_option()]}. --doc(#{title => +-doc(#{group => <<"Client and Server Options">>}). -doc """ Common certificate related options to both client and server. @@ -916,7 +898,7 @@ Common certificate related options to both client and server. {partial_chain, anchor_fun()}. --doc(#{title => +-doc(#{group => <<"Client and Server Options">>}). -doc """ Options common to client and server side prior to TLS-1.3. @@ -963,7 +945,7 @@ Options common to client and server side prior to TLS-1.3. {secure_renegotiate, SecureRenegotiate::boolean()} | {user_lookup_fun, {Lookupfun :: fun(), UserState :: any()}}. --doc(#{title => +-doc(#{group => <<"Client and Server Options">>}). -doc """ Common options to both client and server for TLS-1.3. @@ -992,7 +974,7 @@ Common options to both client and server for TLS-1.3. -type common_option_tls13() :: {supported_groups, [group()]} | {key_update_at, KeyUpdateAt::pos_integer()}. --doc(#{title => +-doc(#{group => <<"Client and Server Options">>}). -doc """ Legacy options considered deprecated in favor of other options, @@ -1078,7 +1060,7 @@ hardware security modules (HSM) or trusted platform modules (TPM). [public_key:private_encrypt/4](`public_key:encrypt_private/3`) if legacy versions TLS-1.0 and TLS-1.1 must be supported. """. --doc(#{title => +-doc(#{group => <<"Certificates">>}). -type key() :: {'RSAPrivateKey'| 'DSAPrivateKey' | 'ECPrivateKey' |'PrivateKeyInfo', public_key:der_encoded()} | @@ -1112,7 +1094,7 @@ information. """. --doc(#{title => +-doc(#{group => <<"Certificates">>}). -type cert_key_conf() :: #{cert => public_key:der_encoded() | [public_key:der_encoded()], key => key(), @@ -1154,10 +1136,10 @@ to be actually used, and they may require additional configuration; see [`srp_param_type()`](`t:srp_param_type/0`). """. --doc(#{title => +-doc(#{group => <<"Algorithms">>}). -type cipher_suites() :: ciphers(). --doc(#{title => <<"Algorithms">>}). +-doc(#{group => <<"Algorithms">>}). -doc """ Cipher suite formats. @@ -1169,13 +1151,13 @@ cipher suite option is needed. """. -type ciphers() :: [erl_cipher_suite()] | string(). % (according to old API) exported --doc(#{title => <<"Algorithms">>}). +-doc(#{group => <<"Algorithms">>}). -doc """ Filter that allows you to customize cipher suite list. """. -type cipher_filters() :: list({key_exchange | cipher | mac | prf, fun((kex_algo()|cipher()|hash()|aead|default_prf) -> true | false)}). % exported --doc(#{title => +-doc(#{group => <<"Certificates">>}). -doc """ Options for using built-in CRL cache support. @@ -1224,7 +1206,7 @@ There are two implementations available: -type crl_cache_opts() :: {Module :: atom(), {DbHandle :: internal | term(), Args :: list()}}. --doc(#{title => +-doc(#{group => <<"Certificates">>}). -doc """ Claim an intermediate CA in the chain as trusted. @@ -1239,7 +1221,7 @@ as the trusted anchor and verifies the rest of the chain. """. -type anchor_fun() :: fun(). --doc(#{title => +-doc(#{group => <<"Algorithms">>}). -doc """ Explicitly list acceptable signature algorithms for certificates and handshake @@ -1357,7 +1339,7 @@ certificate signatures. %% ------------------------------------------------------------------------------------------------------- --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -doc """ The following options are specific to the client side, or have different semantics for the client and server: @@ -1389,7 +1371,7 @@ different semantics for the client and server: client_option_legacy() | common_option_legacy(). --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -doc """ Certificate-related options specific to the client side, or with different semantics for the client and server. @@ -1500,7 +1482,7 @@ different semantics for the client and server. {certificate_authorities, boolean()} | {stapling, Stapling:: staple | no_staple | map()}. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -doc """ Options only relevant for TLS-1.3. @@ -1577,7 +1559,7 @@ Options only relevant for TLS-1.3. {middlebox_comp_mode, MiddleBoxMode::boolean()}. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -doc """ Options only relevant to TLS versions prior to TLS-1.3. @@ -1644,7 +1626,7 @@ Options only relevant to TLS versions prior to TLS-1.3. {fallback, LegacyFallback::boolean()}. --doc(#{title => <<"Client and Server Options">>}). +-doc(#{group => <<"Client and Server Options">>}). -doc """ Common options to client and server only valid for DTLS. @@ -1684,7 +1666,7 @@ Common options to client and server only valid for DTLS. -type common_option_dtls() :: {use_srtp, UseSrtp::#{protection_profiles := [binary()], mki => binary()}}. --doc(#{title => <<"Client Options">>}). +-doc(#{group => <<"Client Options">>}). -doc """ Legacy client options. @@ -1719,7 +1701,7 @@ Legacy client options. %% ------------------------------------------------------------------------------------------------------- --doc(#{title => <<"Server Options">>}). +-doc(#{group => <<"Server Options">>}). -doc """ Options specific to the server side, or with different semantics for the client and server. @@ -1817,7 +1799,7 @@ Certificate related options for a server. can verify. """. --doc(#{title => <<"Server Options">>}). +-doc(#{group => <<"Server Options">>}). -type server_option_cert() :: {cacerts, CACerts::[public_key:der_encoded()] | [public_key:combined_cert()]} | {cacertfile, CACertFile::file:filename()} | {verify, Verify:: verify_none | verify_peer} | @@ -1825,7 +1807,7 @@ Certificate related options for a server. {certificate_authorities, ServerCertAuth::boolean()}. --doc(#{title => <<"Server Options">>}). +-doc(#{group => <<"Server Options">>}). -doc """ Options only relevant to TLS versions prior to TLS-1.3. @@ -1895,7 +1877,7 @@ Options only relevant to TLS versions prior to TLS-1.3. {dhfile, DhFile::file:filename()} | {psk_identity, PSKHint::string()}. --doc(#{title => <<"Server Options">>}). +-doc(#{group => <<"Server Options">>}). -doc """ Options only relevant for TLS-1.3. @@ -1999,7 +1981,7 @@ Options only relevant for TLS-1.3. {cookie, Cookie::boolean()} | {early_data, EarlyData::enabled | disabled}. --doc(#{title => <<"Server Options">>}). +-doc(#{group => <<"Server Options">>}). -doc """ Legacy server options. @@ -2019,10 +2001,10 @@ Legacy server options. %% ------------------------------------------------------------------------------------------------------- --doc(#{title => <<"Deprecated">>}). +-doc(#{group => <<"Deprecated">>}). -type prf_random() :: client_random | server_random. % exported --doc(#{title => <<"Socket">>}). +-doc(#{group => <<"Socket">>}). -doc """ Client hello extensions. """. @@ -2036,7 +2018,7 @@ Client hello extensions. elliptic_curves => [public_key:oid()], sni => inet:hostname()}. % exported %% ------------------------------------------------------------------------------------------------------- --doc(#{title => <<"Info">>}). +-doc(#{group => <<"Info">>}). -doc """ Key value list convening some information about the established connection. """. @@ -2048,7 +2030,7 @@ Key value list convening some information about the established connection. connection_info_pre_tls13() | security_info(). --doc(#{title => <<"Info">>}). +-doc(#{group => <<"Info">>}). -doc """ TLS connection information that can be used for NSS key logging. """. @@ -2058,7 +2040,7 @@ TLS connection information that can be used for NSS key logging. {keylog, term()}]. --doc(#{title => <<"Info">>}). +-doc(#{group => <<"Info">>}). -doc """ TLS connection information relevant prior to TLS-1.3. """. @@ -2068,7 +2050,7 @@ TLS connection information relevant prior to TLS-1.3. {ecc, {named_curve, term()}} | {srp_username, term()}]. --doc(#{title => <<"Info">>}). +-doc(#{group => <<"Info">>}). -doc """ TLS connection keys for which information can be retrieved. """. @@ -2094,7 +2076,7 @@ TLS connection keys for which information can be retrieved. %%%-------------------------------------------------------------------- %%% API %%%-------------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, equiv => start(temporary), since => <<"OTP R14B">>}). -spec start() -> ok | {error, reason()}. @@ -2102,7 +2084,7 @@ TLS connection keys for which information can be retrieved. start() -> start(temporary). --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP R14B">>}). -spec start(permanent | transient | temporary) -> ok | {error, reason()}. -doc "Starts the SSL application.". @@ -2119,7 +2101,7 @@ start(Type) -> Stops the SSL application. """. --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP R14B">>}). -spec stop() -> ok. %%-------------------------------------------------------------------- @@ -2127,7 +2109,7 @@ stop() -> application:stop(ssl). -doc(#{equiv => connect(TCPSocket, TLSOptions, infinity)}). --doc(#{title => <<"Client API">>, +-doc(#{group => <<"Client API">>, since => <<"OTP R14B">>}). -spec connect(TCPSocket, TLSOptions) -> {ok, sslsocket()} | @@ -2163,7 +2145,7 @@ connect(Host, Port, TLSOptions, infinity). ``` """. --doc(#{title => <<"Client API">>}). +-doc(#{group => <<"Client API">>}). -spec connect(TCPSocketOrHost, TLSOptionsOrPort, TimeoutOrTLSOptions) -> {ok, sslsocket()} | {ok, sslsocket(), Ext :: protocol_extensions()} | @@ -2190,7 +2172,7 @@ connect(Host, Port, TLSOptions) connect(Host, Port, TLSOptions, infinity). %%-------------------------------------------------------------------- --doc(#{title => <<"Client API">>}). +-doc(#{group => <<"Client API">>}). -doc """ Opens a TLS/DTLS connection to `Host`, `Port`. @@ -2254,7 +2236,7 @@ connect(Host, Port, Options, Timeout) end. %%-------------------------------------------------------------------- --doc(#{title => <<"Server API">>}). +-doc(#{group => <<"Server API">>}). -doc "Creates an SSL listen socket.". -spec listen(Port, Options) -> {ok, ListenSocket} | {error, Reason} when Port::inet:port_number(), @@ -2276,7 +2258,7 @@ listen(Port, Options0) end. %%-------------------------------------------------------------------- --doc(#{title => <<"Server API">>, +-doc(#{group => <<"Server API">>, equiv => transport_accept(ListenSocket, infinity)}). -spec transport_accept(ListenSocket) -> {ok, SslSocket} | {error, Reason} when @@ -2288,7 +2270,7 @@ transport_accept(ListenSocket) -> transport_accept(ListenSocket, infinity). --doc(#{title => <<"Server API">>}). +-doc(#{group => <<"Server API">>}). -doc """ Accepts an incoming connection request on a listen socket. @@ -2324,7 +2306,7 @@ transport_accept(#sslsocket{socket_handle = ListenSocket, end. %% Performs the SSL/TLS/DTLS server-side handshake. --doc(#{title => <<"Server API">>, +-doc(#{group => <<"Server API">>, equiv => handshake(HsSocket, infinity), since => <<"OTP 21.0">>}). -spec handshake(HsSocket) -> {ok, SslSocket} | {ok, SslSocket, Ext} | {error, Reason} when @@ -2364,7 +2346,7 @@ this call is equivalent to: handshake(HsSocket, Options, infinity). ``` """. --doc(#{title => <<"Server API">>, +-doc(#{group => <<"Server API">>, since => <<"OTP 21.0">>}). -spec handshake(HsSocket, OptionsOrTimeout) -> {ok, SslSocket} | {ok, SslSocket, Ext} | {error, Reason} when HsSocket :: sslsocket(), @@ -2413,7 +2395,7 @@ If option `active` is set to `once`, `true`, or an integer value, the process owning the [`sslsocket()`](`t:sslsocket/0`) will receive messages of type [`active_msgs()`](`t:active_msgs/0`). """. --doc(#{title => <<"Server API">>, +-doc(#{group => <<"Server API">>, since => <<"OTP 21.0">>}). -spec handshake(Socket, Options, Timeout) -> {ok, SslSocket} | @@ -2464,7 +2446,7 @@ handshake(Socket, SslOptions, Timeout) %%-------------------------------------------------------------------- -doc(#{equiv => handshake_continue(HsSocket, Options, infinity)}). --doc(#{title => <<"Client and Server API">>, +-doc(#{group => <<"Client and Server API">>, since => <<"OTP 21.0">>}). -spec handshake_continue(HsSocket, Options) -> {ok, SslSocket} | {error, Reason} when @@ -2478,7 +2460,7 @@ handshake_continue(Socket, SSLOptions) -> %%-------------------------------------------------------------------- -doc "Continue the TLS handshake, possibly with new, additional, or changed options.". --doc(#{title => <<"Client and Server API">>, +-doc(#{group => <<"Client and Server API">>, since => <<"OTP 21.0">>}). -spec handshake_continue(HsSocket, Options, Timeout) -> {ok, SslSocket} | {error, Reason} when @@ -2494,7 +2476,7 @@ handshake_continue(Socket, SSLOptions, Timeout) %%-------------------------------------------------------------------- -doc "Cancel the handshake with a fatal `USER_CANCELED` alert.". --doc(#{title => <<"Client and Server API">>, +-doc(#{group => <<"Client and Server API">>, since => <<"OTP 21.0">>}). -spec handshake_cancel(#sslsocket{}) -> any(). %%-------------------------------------------------------------------- @@ -2502,7 +2484,7 @@ handshake_cancel(Socket) -> ssl_gen_statem:handshake_cancel(Socket). %%-------------------------------------------------------------------- --doc(#{title => <<"Client and Server API">>}). +-doc(#{group => <<"Client and Server API">>}). -doc "Closes a TLS/DTLS connection.". -spec close(SslSocket) -> ok | {error, Reason} when SslSocket :: sslsocket(), @@ -2531,7 +2513,7 @@ In case of downgrade, the close function might return some binary data that should be treated by the user as the first bytes received on the downgraded connection. """. --doc(#{title => <<"Client and Server API">>, +-doc(#{group => <<"Client and Server API">>, since => <<"OTP 18.1">>}). -spec close(SslSocket, How) -> ok | {ok, port()} | {ok, port(), Data} | {error,Reason} when SslSocket :: sslsocket(), @@ -2562,7 +2544,7 @@ close(#sslsocket{socket_handle = ListenSocket, tls_socket:close(Transport, ListenSocket). %%-------------------------------------------------------------------- --doc(#{title => <<"Client and Server API">>}). +-doc(#{group => <<"Client and Server API">>}). -spec send(SslSocket, Data) -> ok | {error, reason()} when SslSocket :: sslsocket(), Data :: iodata(). @@ -2597,7 +2579,7 @@ send(#sslsocket{socket_handle = ListenSocket, tls_socket:send(Transport, ListenSocket, Data). %% {error,enotconn} %%-------------------------------------------------------------------- --doc(#{title => <<"Client and Server API">>, +-doc(#{group => <<"Client and Server API">>, equiv => recv(Socket, Length, infinity)}). -spec recv(SslSocket, Length) -> {ok, Data} | {error, reason()} when SslSocket :: sslsocket(), @@ -2609,7 +2591,7 @@ recv(Socket, Length) -> recv(Socket, Length, infinity). %%-------------------------------------------------------------------- --doc(#{title => <<"Client and Server API">>}). +-doc(#{group => <<"Client and Server API">>}). -spec recv(SslSocket, Length, Timeout) -> {ok, Data} | {error, reason()} when SslSocket :: sslsocket(), Length :: non_neg_integer(), @@ -2642,7 +2624,7 @@ recv(#sslsocket{socket_handle = Listen, Transport:recv(Listen, 0). %% {error,enotconn} %%-------------------------------------------------------------------- --doc(#{title => <<"Client and Server API">>}). +-doc(#{group => <<"Client and Server API">>}). -doc """ Assigns a new controlling process to the SSL socket. @@ -2672,7 +2654,7 @@ controlling_process(#sslsocket{socket_handle = Listen, Transport:controlling_process(Listen, NewController). %%-------------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>}). +-doc(#{group => <<"Utility Functions">>}). -doc """ Returns the most relevant information about the connection. @@ -2717,7 +2699,7 @@ set to `true`. > > If only undefined options are requested the resulting list can be empty. """. --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 18.0">>}). -spec connection_information(SslSocket, Items) -> {ok, Result} | {error, reason()} when SslSocket :: sslsocket(), @@ -2737,7 +2719,7 @@ connection_information(#sslsocket{connection_handler = Controller}, Items) end. %%-------------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>}). +-doc(#{group => <<"Utility Functions">>}). -doc "Returns the address and port number of the peer.". -spec peername(SslSocket) -> {ok, {Address, Port}} | {error, reason()} when @@ -2766,7 +2748,7 @@ peername(#sslsocket{socket_handle = ListenSocket, tls_socket:peername(Transport, ListenSocket). %% Will return {error, enotconn} %%-------------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>}). +-doc(#{group => <<"Utility Functions">>}). -doc """ The peer certificate is returned as a DER-encoded binary. @@ -2793,7 +2775,7 @@ peercert(#sslsocket{listener_config = #config{}}) -> %%-------------------------------------------------------------------- -doc "Returns the protocol negotiated through ALPN or NPN extensions.". --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 18.0">>}). -spec negotiated_protocol(SslSocket) -> {ok, Protocol} | {error, Reason} when SslSocket :: sslsocket(), @@ -2807,7 +2789,7 @@ negotiated_protocol(#sslsocket{connection_handler = Controller}) when is_pid(Con ssl_gen_statem:negotiated_protocol(Controller). %%-------------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 20.3">>}). -doc """ Lists all available cipher suites corresponding to `Description`. @@ -2852,7 +2834,7 @@ cipher_suites(Description, Version) when Version == 'dtlsv1.2'; Equivalent to `cipher_suites/2`, but lists RFC or OpenSSL string names instead of [`erl_cipher_suite()`](`t:erl_cipher_suite/0`). """. --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 22.0">>}). -spec cipher_suites(Description, Version, StringType) -> [string()] when Description :: default | all | exclusive | anonymous, @@ -2886,7 +2868,7 @@ by the crypto library used by the OTP Crypto application, meaning that [`ssl:filter_cipher_suites(Suites, [])`](`filter_cipher_suites/2`) is equivalent to applying only the filters for crypto library support. """. --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 20.3">>}). -spec filter_cipher_suites(Suites, Filters) -> Ciphers when Suites :: ciphers(), @@ -2918,7 +2900,7 @@ present. `Preferred` can be a list of cipher suites or a list of filters in which case the filters are used on `Suites` to extract the preferred cipher list. """. --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 20.3">>}). -spec prepend_cipher_suites(Preferred, Suites) -> ciphers() when Preferred :: ciphers() | cipher_filters(), @@ -2947,7 +2929,7 @@ be a list of cipher suites or a list of filters in which case the filters are used on `Suites` to extract the deferred cipher list. """. --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 20.3">>}). -spec append_cipher_suites(Deferred, Suites) -> ciphers() when Deferred :: ciphers() | cipher_filters(), @@ -3016,7 +2998,7 @@ rsa_pss_rsae_sha512,rsa_pss_rsae_sha384,rsa_pss_rsae_sha256] > certificate signatures in this version of the protocol. """. --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 26.0">>}). -spec signature_algs(Description, Version) -> signature_algs() when Description :: default | all | exclusive, @@ -3051,7 +3033,7 @@ signature_algs(Description, Version) -> %%-------------------------------------------------------------------- --doc(#{title => <<"Pre TLS-1.3 API">>, +-doc(#{group => <<"Pre TLS-1.3 API">>, since => <<"OTP 19.2">>}). -spec eccs() -> NamedCurves when NamedCurves :: [named_curve()]. @@ -3064,7 +3046,7 @@ eccs() -> tls_v1:ec_curves(all, 'tlsv1.2'). %%-------------------------------------------------------------------- --doc(#{title => <<"Pre TLS-1.3 API">>, +-doc(#{group => <<"Pre TLS-1.3 API">>, since => <<"OTP 19.2">>}). -spec eccs(Version) -> NamedCurves when Version :: 'tlsv1.2' | 'tlsv1.1' | 'tlsv1' | 'dtlsv1.2' | 'dtlsv1', @@ -3089,7 +3071,7 @@ eccs(Other) -> erlang:error({badarg, Other}). %%-------------------------------------------------------------------- --doc(#{title => <<"TLS-1.3 Only API">>, +-doc(#{group => <<"TLS-1.3 Only API">>, since => <<"OTP 27.0">>}). -doc """ Returns all supported groups in TLS 1.3. @@ -3102,7 +3084,7 @@ groups() -> tls_v1:groups(). %%-------------------------------------------------------------------- --doc(#{title => <<"TLS-1.3 Only API">>, +-doc(#{group => <<"TLS-1.3 Only API">>, since => <<"OTP 27.0">>}). -spec groups(Description) -> [group()] when Description :: default. @@ -3117,7 +3099,7 @@ groups(default) -> tls_v1:default_groups(). %%-------------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>}). +-doc(#{group => <<"Utility Functions">>}). -doc """ Gets the values of the specified socket options. """. @@ -3159,7 +3141,7 @@ getopts(#sslsocket{}, OptionTags) -> {error, {options, {socket_options, OptionTags}}}. %%-------------------------------------------------------------------- --doc(#{title => <<"Client and Server API">>}). +-doc(#{group => <<"Client and Server API">>}). -doc "Sets options according to `Options` for socket `SslSocket`.". -spec setopts(SslSocket, Options) -> ok | {error, reason()} when SslSocket :: sslsocket(), @@ -3208,7 +3190,7 @@ setopts(#sslsocket{}, Options) -> {error, {options,{not_a_proplist, Options}}}. %%--------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 19.0">>}). -doc """ Get statistics for the underlying socket. @@ -3222,7 +3204,7 @@ getstat(Socket) -> getstat(Socket, inet:stats()). %%-------------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 19.0">>}). -doc """ Get one or more statistic values for the underlying socket. @@ -3261,7 +3243,7 @@ getstat(#sslsocket{connection_handler = Controller, dtls_socket:getstat(Transport, Socket, Options). %%--------------------------------------------------------------- --doc(#{title => <<"Client and Server API">>, +-doc(#{group => <<"Client and Server API">>, since => <<"OTP R14B">>}). -spec shutdown(SslSocket, How) -> ok | {error, reason()} when SslSocket :: sslsocket(), @@ -3295,7 +3277,7 @@ shutdown(#sslsocket{connection_handler = Controller}, How) when is_pid(Controlle ssl_gen_statem:shutdown(Controller, How). %%-------------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>}). +-doc(#{group => <<"Utility Functions">>}). -doc "Returns the local address and port number of socket `SslSocket`.". -spec sockname(SslSocket) -> {ok, {Address, Port}} | {error, reason()} when @@ -3323,7 +3305,7 @@ sockname(#sslsocket{connection_handler = Controller, tls_socket:sockname(Transport, Socket). %%--------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP R14B">>}). -spec versions() -> [VersionInfo] when VersionInfo :: {ssl_app, string()} | @@ -3387,7 +3369,7 @@ versions() -> ]. %%--------------------------------------------------------------- --doc(#{title => <<"Pre TLS-1.3 API">>, +-doc(#{group => <<"Pre TLS-1.3 API">>, since => <<"OTP R14B">>}). -spec renegotiate(SslSocket) -> ok | {error, reason()} when SslSocket :: sslsocket(). @@ -3442,7 +3424,7 @@ connection. There are two types of key updates: if `Type` is `write`, only the writing key is updated; if `Type` is `read_write`, both the reading and writing keys are updated. """. --doc(#{title => <<"TLS-1.3 Only API">>, +-doc(#{group => <<"TLS-1.3 Only API">>, since => <<"OTP 22.3">>}). -spec update_keys(SslSocket, Type) -> ok | {error, reason()} when SslSocket :: sslsocket(), @@ -3467,7 +3449,7 @@ update_keys(_, _) -> %%-------------------------------------------------------------------- -doc(#{equiv => export_key_materials(TLSSocket, Labels, Contexts, WantedLengths, true), - title => <<"Utility Functions">>, + group => <<"Utility Functions">>, since => <<"OTP 27.0">>}). -spec export_key_materials(SslSocket, Labels, Contexts, WantedLengths) -> {ok, ExportKeyMaterials} | {error, reason()} when @@ -3483,7 +3465,7 @@ export_key_materials(#sslsocket{listener_config = #config{}}, _,_,_) -> {error, enotconn}. %%-------------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 27.0">>}). -spec export_key_materials(SslSocket, Labels, Contexts, WantedLengths, ConsumeSecret) -> {ok, ExportKeyMaterials} | {error, exporter_master_secret_already_consumed | bad_input} when @@ -3517,7 +3499,7 @@ export_key_materials(#sslsocket{socket_handle ={_Listen, #config{}}}, _,_,_, _) {error, enotconn}. %%-------------------------------------------------------------------- --doc(#{title => <<"Deprecated API">>, +-doc(#{group => <<"Deprecated API">>, since => <<"OTP R15B01">>}). -spec prf(SslSocket, Secret, Label, Seed, WantedLength) -> {ok, binary()} | {error, reason()} when @@ -3575,7 +3557,7 @@ prf(Socket, Secret, Label, Context, WantedLength) -> {ok, tls_v1:prf(PRFAlg, Secret, Label, erlang:iolist_to_binary(Context), WantedLength)}. %%-------------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 17.5">>}). -spec clear_pem_cache() -> ok. -doc """ @@ -3593,7 +3575,7 @@ clear_pem_cache() -> ssl_pem_cache:clear(). %%--------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>}). +-doc(#{group => <<"Utility Functions">>}). -doc """ Presents the error returned by an SSL function as a printable string. """. @@ -3607,7 +3589,7 @@ format_error(Reason) -> do_format_error(Reason). %%-------------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 21.0">>}). -spec suite_to_str(CipherSuite) -> string() when CipherSuite :: erl_cipher_suite(). @@ -3620,7 +3602,7 @@ suite_to_str(Cipher) -> ssl_cipher_format:suite_map_to_str(Cipher). %%-------------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 22.0">>}). -spec suite_to_openssl_str(CipherSuite) -> string() when CipherSuite :: erl_cipher_suite(). @@ -3637,7 +3619,7 @@ suite_to_openssl_str(Cipher) -> %% %%-------------------------------------------------------------------- --doc(#{title => <<"Utility Functions">>, +-doc(#{group => <<"Utility Functions">>, since => <<"OTP 22.0">>}). -spec str_to_suite(CipherSuiteName) -> erl_cipher_suite() | {error, {not_recognized, CipherSuiteName}} when CipherSuiteName :: string(). diff --git a/lib/stdlib/src/edlin_expand.erl b/lib/stdlib/src/edlin_expand.erl index 70c41fe8d21f..2b454c858d7b 100644 --- a/lib/stdlib/src/edlin_expand.erl +++ b/lib/stdlib/src/edlin_expand.erl @@ -941,48 +941,54 @@ get_exports(Mod) -> [] end end. - -expand_function_name(ModStr, FuncPrefix, CompleteChar, FT) -> +pp(String) when is_binary(String) -> + binary_to_list(string:titlecase(string:trim(String))); +pp(String) when is_list(String) -> + string:titlecase(string:trim(String)). +expand_name(ModStr, Type, Prefix, CompleteChar, FT) -> case to_atom(ModStr) of {ok, Mod} -> - Extra = case Mod of - shell_default -> [{Name, Arity}||{{function, {_, Name, Arity}}, _} <- FT]; - _ -> [] - end, - Exports = get_exports(Mod) ++ Extra, - {Res, Expansion, Matches}=Result = match(FuncPrefix, Exports, CompleteChar), - case Matches of - [] -> Result; - _ -> {Res, Expansion, [#{title=>"functions", elems=>Matches, options=>[highlight_all]}]} - end; - error -> - {no, [], []} - end. - -get_module_types(Mod) -> - case code:get_doc(Mod, #{sources => [debug_info]}) of - {ok, #docs_v1{ docs = Docs } } -> - [{T, A} || {{type, T, A},_Anno,_Sig,_Doc,_Meta} <- Docs]; - _ -> {no, [], []} - end. - -expand_type_name(ModStr, TypePrefix, CompleteChar) -> - case to_atom(ModStr) of - {ok, Mod} -> - case get_module_types(Mod) of - {no, [], []} -> - {no, [], []}; - Types -> - {Res, Expansion, Matches}=Result = match(TypePrefix, Types, CompleteChar), + case Mod =:= shell_default of + true -> ShellDefaultStr = pp("shell defined "++atom_to_list(Type)++"s"), + Groups = #{ShellDefaultStr=>[{Name, Arity}||{{Type1, {_, Name, Arity}}, _} <- FT, Type1 =:= Type]}; + false -> + TypeStr = pp(atom_to_list(Type)++"s"), + case code:get_doc(Mod) of + {ok, #docs_v1{ docs = Docs } } -> + case Type of + function -> + Exports = get_exports(Mod), + Grouped = [{pp(G),{Name,Arity}} || {{Type1,Name,Arity},_,_,_,#{group := G}}<-Docs, Type1 =:= Type, lists:member({Name,Arity},Exports)], + Ungrouped = [{TypeStr,{Name,Arity}} || {{Type1,Name,Arity},_,_,_,MD}<-Docs, Type1 =:= Type, maps:is_key(group, MD) =:= false, lists:member({Name,Arity},Exports)]; + type -> + Grouped = [{pp(G),{Name,Arity}} || {{Type1,Name,Arity},_,_,_,#{exported := true, group := G}}<-Docs, Type1 =:= Type], + Ungrouped = [{TypeStr,{Name,Arity}} || {{Type1,Name,Arity},_,_,_,#{exported := true}=MD}<-Docs, Type1 =:= Type, maps:is_key(group, MD) =:= false] + end, + Groups = maps:groups_from_list(fun (T)->element(1,T) end, + fun(T)->element(2,T) end, + Grouped ++ Ungrouped); + _ when Type =:= function -> + Groups = #{TypeStr => get_exports(Mod)}; + _ -> %% No docs? + Groups = #{} + end + end, + fold_results( + [begin + {Res, Expansion, Matches}=Result = match(Prefix, maps:get(Title, Groups), CompleteChar), case Matches of [] -> Result; - _ -> {Res, Expansion, [#{title=>"types", elems=>Matches, options=>[highlight_all]}]} + _ -> + {Res, Expansion, [#{title=>Title, elems=>Matches, options=>[highlight_all]}]} end - end; + end || Title <- maps:keys(Groups)]); error -> {no, [], []} end. - +expand_function_name(ModStr, FuncPrefix, CompleteChar, FT) -> + expand_name(ModStr, function, FuncPrefix, CompleteChar, FT). +expand_type_name(ModStr, TypePrefix, CompleteChar) -> + expand_name(ModStr, type, TypePrefix, CompleteChar, []). to_atom(Str) -> case erl_scan:string(Str) of {ok, [{atom,_,A}], _} -> diff --git a/lib/stdlib/src/gen_fsm.erl b/lib/stdlib/src/gen_fsm.erl index 5febc76ff98e..80e7b39384a7 100644 --- a/lib/stdlib/src/gen_fsm.erl +++ b/lib/stdlib/src/gen_fsm.erl @@ -270,8 +270,6 @@ for the functions to be exported from a `gen_fsm` callback module. **State data** denotes the internal state of the Erlang process that implements the state machine. """. --moduledoc #{titles => - [{callback, ~"deprecated"}]}. %%%----------------------------------------------------------------- %%% @@ -395,7 +393,7 @@ that implements the state machine. -doc "Reply destination. See `reply/2`". -type from() :: {To :: pid(), Tag :: term()}. --doc #{ title => ~"deprecated" }. +-doc(#{group => ~"deprecated" }). -doc """ Initialize process and internal [*state name*](#state-name) and [*state data*](#state-data). @@ -438,7 +436,7 @@ where `Reason` is any term, or `ignore`. Timeout :: timeout(), Reason :: term(). --doc #{ title => ~"deprecated" }. +-doc(#{group => ~"deprecated" }). -doc """ Handle an asynchronous event. @@ -480,7 +478,7 @@ and terminates. Timeout :: timeout(), Reason :: term(). --doc #{ title => ~"deprecated" }. +-doc(#{group => ~"deprecated" }). -doc """ Handle a synchronous event. @@ -544,7 +542,7 @@ of the process that called [`sync_send_event/2,3`](`sync_send_event/3`), Timeout :: timeout(), Reason :: 'normal' | term(). --doc #{ title => ~"deprecated" }. +-doc(#{group => ~"deprecated" }). -doc """ Handle an asynchronous event. @@ -570,7 +568,7 @@ see [`Module:StateName/2`](`c:'StateName'/2`). Timeout :: timeout(), Reason :: term(). --doc #{ title => ~"deprecated" }. +-doc(#{group => ~"deprecated" }). -doc """ Handle a synchronous event. @@ -602,7 +600,7 @@ see [`Module:StateName/3`](`c:'StateName'/3`). NewStateData :: term(), Timeout :: timeout(), Reason :: term(). --doc #{ title => ~"deprecated" }. +-doc(#{group => ~"deprecated" }). -doc """ Handle an incoming message @@ -627,7 +625,7 @@ see [`Module:StateName/2`](`c:'StateName'/2`). NewStateData :: term(), Timeout :: timeout(), Reason :: normal | term(). --doc #{ title => ~"deprecated" }. +-doc(#{group => ~"deprecated" }). -doc """ Clean up before termination. @@ -672,7 +670,7 @@ using `error_logger:format/2`. StateName :: atom(), StateData :: term(). --doc #{ title => ~"deprecated" }. +-doc(#{group => ~"deprecated" }). -doc """ Update the internal [*state data*](#state-data) during upgrade/downgrade. @@ -708,7 +706,7 @@ and updated internal data. NewStateData :: term(), Extra :: term(). --doc #{ title => ~"deprecated" }. +-doc(#{group => ~"deprecated" }). -doc """ Optional function for providing a term describing the current `gen_fsm` process status. diff --git a/lib/stdlib/src/queue.erl b/lib/stdlib/src/queue.erl index 925b79d7a05d..c1e53a934322 100644 --- a/lib/stdlib/src/queue.erl +++ b/lib/stdlib/src/queue.erl @@ -70,10 +70,6 @@ Okasaki. It regards queues as lists. This API is by many regarded as strange and avoidable. For example, many reverse operations have lexically reversed names, some with more readable but perhaps less understandable aliases. """. --moduledoc(#{titles => - [{function,<<"Original API">>}, - {function,<<"Extended API">>}, - {function,<<"Okasaki API">>}]}). %% Creation, inspection and conversion -export([new/0,is_queue/1,is_empty/1,len/1,to_list/1,from_list/1,member/2]). @@ -117,7 +113,7 @@ some with more readable but perhaps less understandable aliases. %% O(1) -doc "Returns an empty queue.". --doc(#{title => <<"Original API">>}). +-doc(#{group => <<"Original API">>}). -spec new() -> queue(none()). new() -> {[],[]}. %{RearList,FrontList} @@ -128,7 +124,7 @@ that the test will return `true` for a term coinciding with the representation of a queue, even when not constructed by thus module. See also note on [data types](`e:system:data_types.md#no_user_types`). """. --doc(#{title => <<"Original API">>}). +-doc(#{group => <<"Original API">>}). -spec is_queue(Term :: term()) -> boolean(). is_queue({R,F}) when is_list(R), is_list(F) -> true; @@ -137,7 +133,7 @@ is_queue(_) -> %% O(1) -doc "Tests if `Q` is empty and returns `true` if so, otherwise `false`.". --doc(#{title => <<"Original API">>}). +-doc(#{group => <<"Original API">>}). -spec is_empty(Q :: queue()) -> boolean(). is_empty({[],[]}) -> true; @@ -148,7 +144,7 @@ is_empty(Q) -> %% O(len(Q)) -doc "Calculates and returns the length of queue `Q`.". --doc(#{title => <<"Original API">>}). +-doc(#{group => <<"Original API">>}). -spec len(Q :: queue()) -> non_neg_integer(). len({R,F}) when is_list(R), is_list(F) -> length(R)+length(F); @@ -169,7 +165,7 @@ _Example:_ true ``` """. --doc(#{title => <<"Original API">>}). +-doc(#{group => <<"Original API">>}). -spec to_list(Q :: queue(Item)) -> list(Item). to_list({In,Out}) when is_list(In), is_list(Out) -> Out++lists:reverse(In, []); @@ -183,7 +179,7 @@ to_list(Q) -> Returns a queue containing the items in `L` in the same order; the head item of the list becomes the front item of the queue. """. --doc(#{title => <<"Original API">>}). +-doc(#{group => <<"Original API">>}). -spec from_list(L :: list(Item)) -> queue(Item). from_list(L) when is_list(L) -> f2r(L); @@ -194,7 +190,7 @@ from_list(L) -> %% %% O(length(Q)) worst case -doc "Returns `true` if `Item` matches some element in `Q`, otherwise `false`.". --doc(#{title => <<"Original API">>}). +-doc(#{group => <<"Original API">>}). -spec member(Item, Q :: queue(Item)) -> boolean(). member(X, {R,F}) when is_list(R), is_list(F) -> lists:member(X, R) orelse lists:member(X, F); @@ -222,7 +218,7 @@ _Example:_ [1,2,3,4,5,100] ``` """. --doc(#{title => <<"Original API">>}). +-doc(#{group => <<"Original API">>}). -spec in(Item, Q1 :: queue(Item)) -> Q2 :: queue(Item). in(X, {[_]=In,[]}) -> {[X], In}; @@ -249,7 +245,7 @@ _Example:_ [100,1,2,3,4,5] ``` """. --doc(#{title => <<"Original API">>}). +-doc(#{group => <<"Original API">>}). -spec in_r(Item, Q1 :: queue(Item)) -> Q2 :: queue(Item). in_r(X, {[],[_]=F}) -> {F,[X]}; @@ -277,7 +273,7 @@ _Example:_ [2,3,4,5] ``` """. --doc(#{title => <<"Original API">>}). +-doc(#{group => <<"Original API">>}). -spec out(Q1 :: queue(Item)) -> {{value, Item}, Q2 :: queue(Item)} | {empty, Q1 :: queue(Item)}. @@ -314,7 +310,7 @@ _Example:_ [1,2,3,4] ``` """. --doc(#{title => <<"Original API">>}). +-doc(#{group => <<"Original API">>}). -spec out_r(Q1 :: queue(Item)) -> {{value, Item}, Q2 :: queue(Item)} | {empty, Q1 :: queue(Item)}. @@ -352,7 +348,7 @@ _Example 1:_ true ``` """. --doc(#{title => <<"Extended API">>}). +-doc(#{group => <<"Extended API">>}). -spec get(Q :: queue(Item)) -> Item. get({[],[]}=Q) -> erlang:error(empty, [Q]); @@ -386,7 +382,7 @@ _Example 1:_ true ``` """. --doc(#{title => <<"Extended API">>}). +-doc(#{group => <<"Extended API">>}). -spec get_r(Q :: queue(Item)) -> Item. get_r({[],[]}=Q) -> erlang:error(empty, [Q]); @@ -417,7 +413,7 @@ empty {value, 1} ``` """. --doc(#{title => <<"Extended API">>}). +-doc(#{group => <<"Extended API">>}). -spec peek(Q :: queue(Item)) -> empty | {value, Item}. peek({[],[]}) -> empty; @@ -448,7 +444,7 @@ empty {value, 5} ``` """. --doc(#{title => <<"Extended API">>}). +-doc(#{group => <<"Extended API">>}). -spec peek_r(Q :: queue(Item)) -> empty | {value, Item}. peek_r({[],[]}) -> empty; @@ -480,7 +476,7 @@ _Example:_ [2,3,4,5] ``` """. --doc(#{title => <<"Extended API">>}). +-doc(#{group => <<"Extended API">>}). -spec drop(Q1 :: queue(Item)) -> Q2 :: queue(Item). drop({[],[]}=Q) -> erlang:error(empty, [Q]); @@ -515,7 +511,7 @@ _Example:_ [1,2,3,4] ``` """. --doc(#{title => <<"Extended API">>}). +-doc(#{group => <<"Extended API">>}). -spec drop_r(Q1 :: queue(Item)) -> Q2 :: queue(Item). drop_r({[],[]}=Q) -> erlang:error(empty, [Q]); @@ -538,7 +534,7 @@ drop_r(Q) -> %% %% O(1) -doc "Returns a queue `Q2` containing the items of `Q1` in the reverse order.". --doc(#{title => <<"Original API">>}). +-doc(#{group => <<"Original API">>}). -spec reverse(Q1 :: queue(Item)) -> Q2 :: queue(Item). reverse({R,F}) when is_list(R), is_list(F) -> {F,R}; @@ -564,7 +560,7 @@ _Example:_ [1,3,2,4] ``` """. --doc(#{title => <<"Original API">>}). +-doc(#{group => <<"Original API">>}). -spec join(Q1 :: queue(Item), Q2 :: queue(Item)) -> Q3 :: queue(Item). join({R,F}=Q, {[],[]}) when is_list(R), is_list(F) -> Q; @@ -580,7 +576,7 @@ join(Q1, Q2) -> %% N = 0..len(Q) %% O(max(N, len(Q))) -doc "Splits `Q1` in two. The `N` front items are put in `Q2` and the rest in `Q3`.". --doc(#{title => <<"Original API">>}). +-doc(#{group => <<"Original API">>}). -spec split(N :: non_neg_integer(), Q1 :: queue(Item)) -> {Q2 :: queue(Item),Q3 :: queue(Item)}. split(0, {R,F}=Q) when is_list(R), is_list(F) -> @@ -657,7 +653,7 @@ _Example 2:_ [1,2,2,3,3,4,4,5,5,6] ``` """. --doc(#{title => <<"Original API">>}). +-doc(#{group => <<"Original API">>}). -spec filter(Fun, Q1 :: queue(Item)) -> Q2 :: queue(Item) when Fun :: fun((Item) -> boolean() | list(Item)). filter(Fun, {R0,F0}) when is_function(Fun, 1), is_list(R0), is_list(F0) -> @@ -735,7 +731,7 @@ _Example 1:_ "efghi ``` """. --doc(#{title => <<"Original API">>,since => <<"OTP 24.0">>}). +-doc(#{group => <<"Original API">>,since => <<"OTP 24.0">>}). -spec filtermap(Fun, Q1) -> Q2 when Fun :: fun((Item) -> boolean() | {'true', Value}), Q1 :: queue(Item), @@ -788,7 +784,7 @@ _Example:_ 120 ``` """. --doc(#{title => <<"Original API">>,since => <<"OTP 24.0">>}). +-doc(#{group => <<"Original API">>,since => <<"OTP 24.0">>}). -spec fold(Fun, Acc0, Q :: queue(Item)) -> Acc1 when Fun :: fun((Item, AccIn) -> AccOut), Acc0 :: term(), @@ -818,7 +814,7 @@ false true ``` """. --doc(#{title => <<"Original API">>,since => <<"OTP 24.0">>}). +-doc(#{group => <<"Original API">>,since => <<"OTP 24.0">>}). -spec any(Pred, Q :: queue(Item)) -> boolean() when Pred :: fun((Item) -> boolean()). any(Pred, {R, F}) when is_function(Pred, 1), is_list(R), is_list(F) -> @@ -844,7 +840,7 @@ false true ``` """. --doc(#{title => <<"Original API">>,since => <<"OTP 24.0">>}). +-doc(#{group => <<"Original API">>,since => <<"OTP 24.0">>}). -spec all(Pred, Q :: queue(Item)) -> boolean() when Pred :: fun((Item) -> boolean()). all(Pred, {R, F}) when is_function(Pred, 1), is_list(R), is_list(F) -> @@ -870,7 +866,7 @@ _Example:_ false ``` """. --doc(#{title => <<"Original API">>,since => <<"OTP 24.0">>}). +-doc(#{group => <<"Original API">>,since => <<"OTP 24.0">>}). -spec delete(Item, Q1) -> Q2 when Item :: T, Q1 :: queue(T), @@ -912,7 +908,7 @@ _Example:_ [1,2,3,4,5] ``` """. --doc(#{title => <<"Original API">>,since => <<"OTP 24.0">>}). +-doc(#{group => <<"Original API">>,since => <<"OTP 24.0">>}). -spec delete_r(Item, Q1) -> Q2 when Item :: T, Q1 :: queue(T), @@ -963,7 +959,7 @@ _Example:_ [1,2,3,4,5] ``` """. --doc(#{title => <<"Original API">>,since => <<"OTP 24.0">>}). +-doc(#{group => <<"Original API">>,since => <<"OTP 24.0">>}). -spec delete_with(Pred, Q1) -> Q2 when Pred :: fun((Item) -> boolean()), Q1 :: queue(Item), @@ -1005,7 +1001,7 @@ _Example:_ [1,2,3,4,5] ``` """. --doc(#{title => <<"Original API">>,since => <<"OTP 24.0">>}). +-doc(#{group => <<"Original API">>,since => <<"OTP 24.0">>}). -spec delete_with_r(Pred, Q1) -> Q2 when Pred :: fun((Item) -> boolean()), Q1 :: queue(Item), @@ -1093,7 +1089,7 @@ _Example:_ [0,1,2,3] ``` """. --doc(#{title => <<"Okasaki API">>}). +-doc(#{group => <<"Okasaki API">>}). -spec cons(Item, Q1 :: queue(Item)) -> Q2 :: queue(Item). cons(X, Q) -> in_r(X, Q). @@ -1115,7 +1111,7 @@ _Example 1:_ 1 ``` """. --doc(#{title => <<"Okasaki API">>}). +-doc(#{group => <<"Okasaki API">>}). -spec head(Q :: queue(Item)) -> Item. head({[],[]}=Q) -> erlang:error(empty, [Q]); @@ -1131,7 +1127,7 @@ Returns a queue `Q2` that is the result of removing the head item from `Q1`. Fails with reason `empty` if `Q1` is empty. """. --doc(#{title => <<"Okasaki API">>}). +-doc(#{group => <<"Okasaki API">>}). -spec tail(Q1 :: queue(Item)) -> Q2 :: queue(Item). tail(Q) -> drop(Q). @@ -1152,7 +1148,7 @@ _Example:_ [1,2,3,4] ``` """. --doc(#{title => <<"Okasaki API">>}). +-doc(#{group => <<"Okasaki API">>}). -spec snoc(Q1 :: queue(Item), Item) -> Q2 :: queue(Item). snoc(Q, X) -> in(X, Q). @@ -1170,7 +1166,7 @@ _Example 1:_ 3 ``` """. --doc(#{title => <<"Okasaki API">>}). +-doc(#{group => <<"Okasaki API">>}). -spec daeh(Q :: queue(Item)) -> Item. daeh(Q) -> get_r(Q). -doc """ @@ -1185,7 +1181,7 @@ _Example:_ 3 ``` """. --doc(#{title => <<"Okasaki API">>}). +-doc(#{group => <<"Okasaki API">>}). -spec last(Q :: queue(Item)) -> Item. last(Q) -> get_r(Q). @@ -1204,7 +1200,7 @@ _Example:_ [1,2] ``` """. --doc(#{title => <<"Okasaki API">>}). +-doc(#{group => <<"Okasaki API">>}). -spec liat(Q1 :: queue(Item)) -> Q2 :: queue(Item). liat(Q) -> drop_r(Q). -doc """ @@ -1214,7 +1210,7 @@ Fails with reason `empty` if `Q1` is empty. The name [`lait/1`](`lait/1`) is a misspelling - do not use it anymore. """. --doc(#{title => <<"Okasaki API">>}). +-doc(#{group => <<"Okasaki API">>}). -spec lait(Q1 :: queue(Item)) -> Q2 :: queue(Item). lait(Q) -> drop_r(Q). %% Oops, mis-spelled 'tail' reversed. Forget this one. -doc """ @@ -1231,7 +1227,7 @@ _Example:_ [1,2] ``` """. --doc(#{title => <<"Okasaki API">>}). +-doc(#{group => <<"Okasaki API">>}). -spec init(Q1 :: queue(Item)) -> Q2 :: queue(Item). init(Q) -> drop_r(Q). diff --git a/lib/stdlib/src/rand.erl b/lib/stdlib/src/rand.erl index 3b93fdbb4ad8..f8ecb388a91a 100644 --- a/lib/stdlib/src/rand.erl +++ b/lib/stdlib/src/rand.erl @@ -394,10 +394,7 @@ the generator's range: This will create a value of the form N*2^-53 with equal probability for every possible N for the range. """. --moduledoc(#{since => "OTP 18.0", - titles => - [{function,<<"Plug-in framework API">>}, - {function,<<"Niche algorithms API">>}]}). +-moduledoc(#{since => "OTP 18.0"}). -export([seed_s/1, seed_s/2, seed/1, seed/2, export_seed/0, export_seed_s/1, @@ -638,7 +635,7 @@ Export the seed value. Returns the random number state in an external format. To be used with `seed/1`. """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). -spec export_seed() -> 'undefined' | export_state(). export_seed() -> case get(?SEED_DICT) of @@ -652,7 +649,7 @@ Export the seed value. Returns the random number generator state in an external format. To be used with `seed/1`. """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). -spec export_seed_s(State :: state()) -> export_state(). export_seed_s({#{type:=Alg}, AlgState}) -> {Alg, AlgState}. @@ -673,7 +670,7 @@ The argument `default` is an alias for the [_default algorithm_](#default-algorithm) that has been implemented *(Since OTP 24.0)*. """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). -spec seed(Alg_or_State :: term()) -> state(). seed(Alg_or_State) -> seed_put(seed_s(Alg_or_State)). @@ -691,7 +688,7 @@ generation with reasonably unpredictable time dependent data. With the argument `State`, re-creates the state and returns it. See also `export_seed/0`. """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). -spec seed_s(Alg | State) -> state() when Alg :: builtin_alg() | 'default', State :: state() | export_state(). @@ -721,7 +718,7 @@ but also stores the generated state in the process dictionary. [_default algorithm_](#default-algorithm) that has been implemented *(Since OTP 24.0)*. """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). -spec seed(Alg :: term(), Seed :: term()) -> state(). seed(Alg, Seed) -> seed_put(seed_s(Alg, Seed)). @@ -735,7 +732,7 @@ from the specified `t:seed/0` integers. `Alg = default` is an alias for the [_default algorithm_](#default-algorithm) that has been implemented *since OTP 24.0*. """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). -spec seed_s(Alg, Seed) -> state() when Alg :: builtin_alg() | 'default', Seed :: seed(). @@ -758,7 +755,7 @@ using the state in the process dictionary. Like `uniform_s/1` but operates on the state stored in the process dictionary. Returns the generated number `X`. """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). -spec uniform() -> X :: float(). uniform() -> {X, State} = uniform_s(seed_get()), @@ -776,7 +773,7 @@ using the state in the process dictionary. Like `uniform_s/2` but operates on the state stored in the process dictionary. Returns the generated number `X`. """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). -spec uniform(N :: pos_integer()) -> X :: pos_integer(). uniform(N) -> {X, State} = uniform_s(N, seed_get()), @@ -814,7 +811,7 @@ equally spaced in the interval. > end. > ``` """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). -spec uniform_s(State :: state()) -> {X :: float(), NewState :: state()}. uniform_s(State = {#{uniform:=Uniform}, _}) -> Uniform(State); @@ -839,7 +836,7 @@ From the specified `State`, generates a random number `X ::` `t:integer/0`, uniformly distributed in the specified range `1 =< X =< N`. Returns the number `X` and the updated `NewState`. """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). -spec uniform_s(N :: pos_integer(), State :: state()) -> {X :: pos_integer(), NewState :: state()}. uniform_s(N, State = {#{uniform_n:=UniformN}, _}) @@ -875,7 +872,7 @@ the process dictionary. Returns the generated number `X`. See `uniform_real_s/1`. """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 21.0">>}). -spec uniform_real() -> X :: float(). uniform_real() -> {X, Seed} = uniform_real_s(seed_get()), @@ -953,7 +950,7 @@ Having to generate extra random bits for occasional small numbers costs a little performance. This function is about 20% slower than the regular `uniform_s/1` """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 21.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 21.0">>}). -spec uniform_real_s(State :: state()) -> {X :: float(), NewState :: state()}. uniform_real_s({#{bits:=Bits, next:=Next} = AlgHandler, R0}) -> %% Generate a 56 bit number without using the weak low bits. @@ -1110,7 +1107,7 @@ using the state in the process dictionary. Like `bytes_s/2` but operates on the state stored in the process dictionary. Returns the generated [`Bytes`](`t:binary/0`). """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 24.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 24.0">>}). -spec bytes(N :: non_neg_integer()) -> Bytes :: binary(). bytes(N) -> {Bytes, State} = bytes_s(N, seed_get()), @@ -1131,7 +1128,7 @@ The selected algorithm is used to generate as many random numbers as required to compose the `t:binary/0`. Returns the generated [`Bytes`](`t:binary/0`) and a [`NewState`](`t:state/0`). """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 24.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 24.0">>}). -spec bytes_s(N :: non_neg_integer(), State :: state()) -> {Bytes :: binary(), NewState :: state()}. bytes_s(N, {#{bits:=Bits, next:=Next} = AlgHandler, R}) @@ -1210,7 +1207,7 @@ random number sequences from one start state. This function raises a `not_implemented` error exception if there is no jump function implemented for the [`State`](`t:state/0`)'s algorithm. """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 20.0">>}). -spec jump(State :: state()) -> NewState :: state(). jump(State = {#{jump:=Jump}, _}) -> Jump(State); @@ -1229,7 +1226,7 @@ Jump the generator state forward. Like `jump/1` but operates on the state stored in the process dictionary. Returns the [`NewState`](`t:state/0`). """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 20.0">>}). -spec jump() -> NewState :: state(). jump() -> seed_put(jump(seed_get())). @@ -1243,7 +1240,7 @@ Generate a random number with standard normal distribution. Like `normal_s/1` but operates on the state stored in the process dictionary. Returns the generated number `X`. """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). -spec normal() -> X :: float(). normal() -> {X, Seed} = normal_s(seed_get()), @@ -1259,7 +1256,7 @@ Generate a random number with specified normal distribution 𝒩 *(μ, σ²)*. Like `normal_s/3` but operates on the state stored in the process dictionary. Returns the generated number `X`. """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 20.0">>}). -spec normal(Mean :: number(), Variance :: number()) -> X :: float(). normal(Mean, Variance) -> Mean + (math:sqrt(Variance) * normal()). @@ -1278,7 +1275,7 @@ and variance `1.0`. Returns the generated number [`X`](`t:float/0`) and the [`NewState`](`t:state/0`). """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 18.0">>}). -spec normal_s(State :: state()) -> {X :: float(), NewState :: state()}. normal_s(State0) -> {Sign, R, State} = get_52(State0), @@ -1306,7 +1303,7 @@ where `Variance >= 0.0`. Returns [`X`](`t:float/0`) and the [`NewState`](`t:state/0`). """. --doc(#{title => <<"Plug-in framework API">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Plug-in framework API">>,since => <<"OTP 20.0">>}). -spec normal_s(Mean, Variance, State) -> {X :: float(), NewState :: state()} when Mean :: number(), @@ -1537,7 +1534,7 @@ with a specific [`Seed`](`t:seed/0`). > > The generator is exported in this form primarily for performance reasons. """. --doc(#{title => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). +-doc(#{group => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). -spec exsp_next(AlgState :: exsplus_state()) -> {X :: uint58(), NewAlgState :: exsplus_state()}. exsp_next([S1|S0]) -> @@ -1636,7 +1633,7 @@ See the description of jump functions at the top of this module description. See `exsp_next/1` about why this internal implementation function has been exposed. """. --doc(#{title => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). +-doc(#{group => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). -spec exsp_jump(AlgState :: exsplus_state()) -> NewAlgState :: exsplus_state(). exsp_jump(S) -> @@ -2251,7 +2248,7 @@ is 60% of the time for the default algorithm generating a `t:float/0`. > it passes strict PRNG tests. The generator is much faster than > `exsp_next/1` but with a bit lower quality and much shorter period. """. --doc(#{title => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). +-doc(#{group => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). -spec mwc59(CX0 :: mwc59_state()) -> CX1 :: mwc59_state(). mwc59(CX) when is_integer(CX), 1 =< CX, CX < ?MWC59_P -> C = CX bsr ?MWC59_B, @@ -2294,7 +2291,7 @@ For a non power of 2 range less than about 16 bits (to not get too much bias and to avoid bignums) truncated multiplication can be used, that is: `(Range*V) bsr 32`, which is much faster than using `rem`. """. --doc(#{title => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). +-doc(#{group => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). -spec mwc59_value32(CX :: mwc59_state()) -> V :: 0..?MASK(32). mwc59_value32(CX1) when is_integer(CX1), 1 =< CX1, CX1 < ?MWC59_P -> CX = ?MASK(32, CX1), @@ -2321,7 +2318,7 @@ the range is 30 bits, we use 29 bits from the generator, adding up to 59 bits, which is not a bignum (on a 64-bit VM ): `(1000000000 * (V bsr (59-29))) bsr 29`. """. --doc(#{title => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). +-doc(#{group => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). -spec mwc59_value(CX :: mwc59_state()) -> V :: 0..?MASK(59). mwc59_value(CX) when is_integer(CX), 1 =< CX, CX < ?MWC59_P -> CX2 = CX bxor ?BSL(59, CX, ?MWC59_XS1), @@ -2336,7 +2333,7 @@ in the range `0.0 =< V < 1.0` like for example `uniform_s/1`. The generator state is scrambled as with [`mwc59_value/1`](`mwc59_value/1`) before converted to a `t:float/0`. """. --doc(#{title => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). +-doc(#{group => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). -spec mwc59_float(CX :: mwc59_state()) -> V :: float(). mwc59_float(CX1) when is_integer(CX1), 1 =< CX1, CX1 < ?MWC59_P -> CX = ?MASK(53, CX1), @@ -2350,7 +2347,7 @@ Create a [MWC59 generator state](`t:mwc59_state/0`). Like `mwc59_seed/1` but it hashes the default seed value of [`seed_s(atom())`](`seed_s/1`). """. --doc(#{title => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). +-doc(#{group => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). -spec mwc59_seed() -> CX :: mwc59_state(). mwc59_seed() -> {A1, A2, A3} = default_seed(), @@ -2366,7 +2363,7 @@ Returns a generator state [`CX`](`t:mwc59_state/0`). The 58-bit seed value `S` is hashed to create the generator state, to avoid that similar seeds create similar sequences. """. --doc(#{title => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). +-doc(#{group => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). -spec mwc59_seed(S :: 0..?MASK(58)) -> CX :: mwc59_state(). mwc59_seed(S) when is_integer(S), 0 =< S, S =< ?MASK(58) -> hash58(S) + 1. @@ -2473,7 +2470,7 @@ This generator is used internally in the `rand` module for seeding other generators since it is of a quite different breed which reduces the probability for creating an accidentally bad seed. """. --doc(#{title => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). +-doc(#{group => <<"Niche algorithms API">>,since => <<"OTP 25.0">>}). -spec splitmix64_next(AlgState :: integer()) -> {X :: uint64(), NewAlgState :: splitmix64_state()}. splitmix64_next(X_0) -> diff --git a/lib/stdlib/src/string.erl b/lib/stdlib/src/string.erl index e047d5cc2d7e..02dd04fae724 100644 --- a/lib/stdlib/src/string.erl +++ b/lib/stdlib/src/string.erl @@ -121,9 +121,6 @@ Some of the general string functions can seem to overlap each other. The reason is that this string package is the combination of two earlier packages and all functions of both packages have been retained. """. --moduledoc(#{titles => - [{function,<<"Functions">>}, - {function,<<"Obsolete API functions">>}]}). -export([is_empty/1, length/1, to_graphemes/1, reverse/1, @@ -231,7 +228,7 @@ false true ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec is_empty(String::unicode:chardata()) -> boolean(). is_empty([]) -> true; is_empty(<<>>) -> true; @@ -251,7 +248,7 @@ _Example:_ 3 ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec length(String::unicode:chardata()) -> non_neg_integer(). length(<>) -> length_b(Bin, CP1, 0); @@ -271,7 +268,7 @@ _Example:_ [223,8593,[101,778]] ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec to_graphemes(String::unicode:chardata()) -> [grapheme_cluster()]. to_graphemes(CD0) -> case unicode_util:gc(CD0) of @@ -283,7 +280,7 @@ to_graphemes(CD0) -> %% Compare two strings return boolean, assumes that the input are %% normalized to same form, see unicode:characters_to_nfX_xxx(..) -doc(#{equiv => equal(A, B, true)}). --doc(#{title => <<"Functions">>}). +-doc(#{group => <<"Functions">>}). -spec equal(A, B) -> boolean() when A::unicode:chardata(), B::unicode:chardata(). @@ -296,7 +293,7 @@ equal(A,B) -> %% normalized to same form, see unicode:characters_to_nfX_xxx(..) %% does casefold on the fly -doc(#{equiv => equal(A, B, IgnoreCase, none)}). --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec equal(A, B, IgnoreCase) -> boolean() when A::unicode:chardata(), B::unicode:chardata(), @@ -332,7 +329,7 @@ false true ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec equal(A, B, IgnoreCase, Norm) -> boolean() when A :: unicode:chardata(), B :: unicode:chardata(), @@ -358,7 +355,7 @@ _Example:_ ÖÄÅ ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec reverse(String::unicode:chardata()) -> [grapheme_cluster()]. reverse(<>) -> reverse_b(Rest, CP1, []); @@ -368,7 +365,7 @@ reverse(CD) -> %% Slice a string and return rest of string %% Note: counts grapheme_clusters -doc(#{equiv => slice(String, Length, infinity)}). --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec slice(String, Start) -> Slice when String::unicode:chardata(), Start :: non_neg_integer(), @@ -394,7 +391,7 @@ _Example:_ "ö Wörld" ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec slice(String, Start, Length) -> Slice when String::unicode:chardata(), Start :: non_neg_integer(), @@ -419,7 +416,7 @@ slice(CD, _, 0) -> %% Pad a string to desired length -doc(#{equiv => pad(String, Length, trailing)}). --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec pad(String, Length) -> unicode:charlist() when String ::unicode:chardata(), Length :: integer(). @@ -427,7 +424,7 @@ pad(CD, Length) -> pad(CD, Length, trailing, $\s). -doc(#{equiv => pad(String, Length, Dir, $\s)}). --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec pad(String, Length, Dir) -> unicode:charlist() when String ::unicode:chardata(), Length :: integer(), @@ -450,7 +447,7 @@ _Example:_ ' He̊llö ' ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec pad(String, Length, Dir, Char) -> unicode:charlist() when String ::unicode:chardata(), Length :: integer(), @@ -474,7 +471,7 @@ pad(CD, Length, both, Char) when is_integer(Length) -> %% Strip characters from whitespace or Separator in Direction -doc(#{equiv => trim(String, both)}). --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec trim(String) -> unicode:chardata() when String :: unicode:chardata(). trim(Str) -> @@ -486,7 +483,7 @@ Equivalent to [`trim(String, Dir, Whitespace})`](`trim/3`) where as Pattern_White_Space in [Unicode Standard Annex #31](http://unicode.org/reports/tr31/). """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec trim(String, Dir) -> unicode:chardata() when String :: unicode:chardata(), Dir :: direction() | 'both'. @@ -514,7 +511,7 @@ _Example:_ <<".Hello">> ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec trim(String, Dir, Characters) -> unicode:chardata() when String :: unicode:chardata(), Dir :: direction() | 'both', @@ -548,14 +545,14 @@ _Example:_ "\nHello\r" ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec chomp(String::unicode:chardata()) -> unicode:chardata(). chomp(Str) -> trim(Str, trailing, [[$\r,$\n],$\n]). %% Split String into two parts where the leading part consists of Characters -doc(#{equiv => take(String, Characters, false)}). --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec take(String, Characters) -> {Leading, Trailing} when String::unicode:chardata(), Characters::[grapheme_cluster()], @@ -564,7 +561,7 @@ chomp(Str) -> take(Str, Sep) -> take(Str, Sep, false, leading). -doc(#{equiv => take(String, Characters, Complement, leading)}). --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec take(String, Characters, Complement) -> {Leading, Trailing} when String::unicode:chardata(), Characters::[grapheme_cluster()], @@ -592,7 +589,7 @@ _Example:_ {<<"abc0z">>,<<"123">>} ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec take(String, Characters, Complement, Dir) -> {Leading, Trailing} when String::unicode:chardata(), Characters::[grapheme_cluster()], @@ -633,7 +630,7 @@ _Example:_ "MICHAŁ" ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec uppercase(String::unicode:chardata()) -> unicode:chardata(). uppercase(CD) when is_list(CD) -> try uppercase_list(CD, false) @@ -664,7 +661,7 @@ _Example:_ "michał" ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec lowercase(String::unicode:chardata()) -> unicode:chardata(). lowercase(CD) when is_list(CD) -> try lowercase_list(CD, false) @@ -692,7 +689,7 @@ _Example:_ "Ss is a SHARP s" ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec titlecase(String::unicode:chardata()) -> unicode:chardata(). titlecase(CD) when is_list(CD) -> case unicode_util:titlecase(CD) of @@ -720,7 +717,7 @@ _Example:_ "ω and ss sharp s" ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec casefold(String::unicode:chardata()) -> unicode:chardata(). casefold(CD) when is_list(CD) -> try casefold_list(CD, false) @@ -754,7 +751,7 @@ _Example:_ {error,no_integer} ``` """. --doc(#{title => <<"Functions">>}). +-doc(#{group => <<"Functions">>}). -spec to_integer(String) -> {Int, Rest} | {'error', Reason} when String :: unicode:chardata(), Int :: integer(), @@ -795,7 +792,7 @@ _Example:_ {-1.5,"eX"} ``` """. --doc(#{title => <<"Functions">>}). +-doc(#{group => <<"Functions">>}). -spec to_float(String) -> {Float, Rest} | {'error', Reason} when String :: unicode:chardata(), Float :: float(), @@ -839,7 +836,7 @@ _Example:_ nomatch ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec prefix(String::unicode:chardata(), Prefix::unicode:chardata()) -> 'nomatch' | unicode:chardata(). prefix(Str, Prefix0) -> @@ -854,7 +851,7 @@ prefix(Str, Prefix0) -> %% split String with the first occurrence of SearchPattern, return list of splits -doc(#{equiv => split(String, SearchPattern, leading)}). --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec split(String, SearchPattern) -> [unicode:chardata()] when String :: unicode:chardata(), SearchPattern :: unicode:chardata(). @@ -878,7 +875,7 @@ _Example:_ [<<"ab">>,<<"bc">>,<<>>,<<"cd">>] ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec split(String, SearchPattern, Where) -> [unicode:chardata()] when String :: unicode:chardata(), SearchPattern :: unicode:chardata(), @@ -898,7 +895,7 @@ split(String, SearchPattern, Where) -> %% Replace the first SearchPattern in String with Replacement -doc(#{equiv => replace(String, SearchPattern, Replacement, leading)}). --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec replace(String, SearchPattern, Replacement) -> [unicode:chardata()] when String :: unicode:chardata(), @@ -927,7 +924,7 @@ _Example:_ [<<"ab">>,"*",<<"cd">>,"*",<<"ef">>] ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec replace(String, SearchPattern, Replacement, Where) -> [unicode:chardata()] when String :: unicode:chardata(), @@ -958,7 +955,7 @@ _Example:_ [<<"abc">>,<<"de̊f"/utf8>>,<<"ghi">>,<<"jkl\r\nfoo">>] ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec lexemes(String::unicode:chardata(), SeparatorList::[grapheme_cluster()]) -> [unicode:chardata()]. @@ -979,7 +976,7 @@ _Example:_ "ghi" ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec nth_lexeme(String, N, SeparatorList) -> unicode:chardata() when String::unicode:chardata(), N::non_neg_integer(), @@ -992,7 +989,7 @@ nth_lexeme(Str, N, Seps0) when is_list(Seps0), is_integer(N), N > 0 -> %% find first SearchPattern in String return rest of string -doc(#{equiv => find(String, SearchPattern, leading)}). --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec find(String, SearchPattern) -> unicode:chardata() | 'nomatch' when String::unicode:chardata(), SearchPattern::unicode:chardata(). @@ -1019,7 +1016,7 @@ nomatch nomatch ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec find(String, SearchPattern, Dir) -> unicode:chardata() | 'nomatch' when String::unicode:chardata(), SearchPattern::unicode:chardata(), @@ -1053,7 +1050,7 @@ _Example:_ The Jaro distance between two strings can be calculated with `JaroDistance = 1.0 - JaroSimilarity`. """. --doc(#{title => <<"Functions">>,since => <<"OTP 27.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 27.0">>}). -spec jaro_similarity(String1, String2) -> Similarity when String1 :: unicode:chardata(), String2 :: unicode:chardata(), @@ -1113,7 +1110,7 @@ _Example:_ ["e̊"|<<"fg">>] ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec next_grapheme(String::unicode:chardata()) -> maybe_improper_list(grapheme_cluster(),unicode:chardata()) | {error,unicode:chardata()}. @@ -1132,7 +1129,7 @@ _Example:_ [101|<<"̊fg"/utf8>>] ``` """. --doc(#{title => <<"Functions">>,since => <<"OTP 20.0">>}). +-doc(#{group => <<"Functions">>,since => <<"OTP 20.0">>}). -spec next_codepoint(String::unicode:chardata()) -> maybe_improper_list(char(),unicode:chardata()) | {error,unicode:chardata()}. @@ -2403,7 +2400,7 @@ Returns the number of characters in `String`. This function is [obsolete](`m:string#obsolete-api-functions`). Use `length/1`. """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec len(String) -> Length when String :: string(), Length :: non_neg_integer(). @@ -2431,7 +2428,7 @@ This function is [obsolete](`m:string#obsolete-api-functions`). Use `[String1, String2]` as `Data` argument, and call `unicode:characters_to_list/2` or `unicode:characters_to_binary/2` to flatten the output. """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec concat(String1, String2) -> String3 when String1 :: string(), String2 :: string(), @@ -2449,7 +2446,7 @@ Returns the index of the first occurrence of `Character` in `String`. Returns This function is [obsolete](`m:string#obsolete-api-functions`). Use `find/2`. """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec chr(String, Character) -> Index when String :: string(), Character :: char(), @@ -2467,7 +2464,7 @@ if `Character` does not occur. This function is [obsolete](`m:string#obsolete-api-functions`). Use `find/3`. """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec rchr(String, Character) -> Index when String :: string(), Character :: char(), @@ -2500,7 +2497,7 @@ _Example:_ 8 ``` """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec str(String, SubString) -> Index when String :: string(), SubString :: string(), @@ -2529,7 +2526,7 @@ _Example:_ 8 ``` """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec rstr(String, SubString) -> Index when String :: string(), SubString :: string(), @@ -2565,7 +2562,7 @@ _Example:_ 5 ``` """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec span(String, Chars) -> Length when String :: string(), Chars :: string(), @@ -2593,7 +2590,7 @@ _Example:_ 0 ``` """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec cspan(String, Chars) -> Length when String :: string(), Chars :: string(), @@ -2613,7 +2610,7 @@ cspan([], _Cs, I) -> I. %% Extract a sub-string from String. -doc(#{equiv => substr(String, Start, string:length(String) - Start)}). --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec substr(String, Start) -> SubString when String :: string(), SubString :: string(), @@ -2637,7 +2634,7 @@ _Example:_ "lo Wo" ``` """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec substr(String, Start, Length) -> SubString when String :: string(), SubString :: string(), @@ -2673,7 +2670,7 @@ resulting list of tokens. This function is [obsolete](`m:string#obsolete-api-functions`). Use `lexemes/2`. """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec tokens(String, SeparatorList) -> Tokens when String :: string(), SeparatorList :: string(), @@ -2723,7 +2720,7 @@ tokens_multiple_2([], _Seps, Toks, Tok) -> [Tok|Toks]. -doc(#{equiv => chars(Character, Number, [])}). --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec chars(Character, Number) -> String when Character :: char(), Number :: non_neg_integer(), @@ -2738,7 +2735,7 @@ string can end with string `Tail`. This function is [obsolete](`m:string#obsolete-api-functions`). Use `lists:duplicate/2`. """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec chars(Character, Number, Tail) -> String when Character :: char(), Number :: non_neg_integer(), @@ -2760,7 +2757,7 @@ Returns a string containing `String` repeated `Number` times. This function is [obsolete](`m:string#obsolete-api-functions`). Use `lists:duplicate/2`. """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec copies(String, Number) -> Copies when String :: string(), Copies :: string(), @@ -2777,7 +2774,7 @@ copies(CharList, Num, R) -> %%% WORDS %%% -doc(#{equiv => words(String, $\s)}). --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec words(String) -> Count when String :: string(), Count :: pos_integer(). @@ -2796,7 +2793,7 @@ _Example:_ 4 ``` """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec words(String, Character) -> Count when String :: string(), Character :: char(), @@ -2812,7 +2809,7 @@ w_count([_H|T], Char, Num) -> w_count(T, Char, Num). %%% SUB_WORDS %%% -doc(#{equiv => sub_word(String, Number, $\s)}). --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec sub_word(String, Number) -> Word when String :: string(), Word :: string(), @@ -2834,7 +2831,7 @@ _Example:_ "ld b" ``` """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec sub_word(String, Number, Character) -> Word when String :: string(), Word :: string(), @@ -2860,13 +2857,13 @@ s_word([_|T],Stop,Char,Index,Res) when Index < Stop -> %%% STRIP %%% -doc(#{equiv => strip(String, both)}). --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec strip(string()) -> string(). strip(String) -> strip(String, both). -doc(#{equiv => strip(String, Direction, $\s)}). --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec strip(String, Direction) -> Stripped when String :: string(), Stripped :: string(), @@ -2894,7 +2891,7 @@ _Example:_ "Hello" ``` """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec strip(String, Direction, Character) -> Stripped when String :: string(), Stripped :: string(), @@ -2924,7 +2921,7 @@ strip_right([], Sc) when is_integer(Sc) -> %%% LEFT %%% -doc(#{equiv => left(String, Number, $\s)}). --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec left(String, Number) -> Left when String :: string(), Left :: string(), @@ -2947,7 +2944,7 @@ _Example:_ "Hello....." ``` """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec left(String, Number, Character) -> Left when String :: string(), Left :: string(), @@ -2967,7 +2964,7 @@ l_pad(String, Num, Char) -> String ++ chars(Char, Num). %%% RIGHT %%% -doc(#{equiv => right(String, Number, $\s)}). --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec right(String, Number) -> Right when String :: string(), Right :: string(), @@ -2989,7 +2986,7 @@ _Example:_ ".....Hello" ``` """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec right(String, Number, Character) -> Right when String :: string(), Right :: string(), @@ -3009,7 +3006,7 @@ r_pad(String, Num, Char) -> chars(Char, Num, String). %%% CENTRE %%% -doc(#{equiv => centre(String, Number, $\s)}). --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec centre(String, Number) -> Centered when String :: string(), Centered :: string(), @@ -3023,7 +3020,7 @@ blanks or `Character`. The resulting string has length `Number`. This function is [obsolete](`m:string#obsolete-api-functions`). Use `pad/3`. """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec centre(String, Number, Character) -> Centered when String :: string(), Centered :: string(), @@ -3045,7 +3042,7 @@ centre(String, Len, Char) when is_integer(Len), is_integer(Char) -> %%% SUB_STRING %%% -doc(#{equiv => sub_string(String, Start, string:length(String))}). --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec sub_string(String, Start) -> SubString when String :: string(), SubString :: string(), @@ -3066,7 +3063,7 @@ _Example:_ "lo Wo" ``` """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec sub_string(String, Start, Stop) -> SubString when String :: string(), SubString :: string(), @@ -3106,7 +3103,7 @@ This function is [obsolete](`m:string#obsolete-api-functions`) use `lowercase/1`, `titlecase/1` or `casefold/1`. """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec to_lower(String) -> Result when String :: io_lib:latin1_string(), Result :: io_lib:latin1_string() @@ -3127,7 +3124,7 @@ set are unchanged. This function is [obsolete](`m:string#obsolete-api-functions`) use `uppercase/1`, `titlecase/1` or `casefold/1`. """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec to_upper(String) -> Result when String :: io_lib:latin1_string(), Result :: io_lib:latin1_string() @@ -3154,7 +3151,7 @@ _Example:_ "one, two, three" ``` """. --doc(#{title => <<"Obsolete API functions">>}). +-doc(#{group => <<"Obsolete API functions">>}). -spec join(StringList, Separator) -> String when StringList :: [string()], Separator :: string(), diff --git a/lib/stdlib/src/sys.erl b/lib/stdlib/src/sys.erl index 2cc0685eb8a9..3620a2d370c2 100644 --- a/lib/stdlib/src/sys.erl +++ b/lib/stdlib/src/sys.erl @@ -73,9 +73,6 @@ Four predefined system events are used when a process receives or sends a message. The process can also define its own system events. It is always up to the process itself to format these events. """. --moduledoc(#{titles => - [{function,<<"Process Implementation Functions">>}, - {callback,<<"Process Implementation Functions">>}]}). -compile(nowarn_deprecated_catch). @@ -220,7 +217,7 @@ function converts argument `Misc` to the new data structure. `OldVsn` is attribute _vsn_ of the old version of the `Module`. If no such attribute is defined, the atom `undefined` is sent. """. --doc(#{title => <<"Process Implementation Functions">>}). +-doc(#{group => <<"Process Implementation Functions">>}). -callback system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc} when Misc :: term(), OldVsn :: undefined | term(), @@ -231,7 +228,7 @@ defined, the atom `undefined` is sent. Called from `handle_system_msg/6` when the process is to continue its execution (for example, after it has been suspended). This function never returns. """. --doc(#{title => <<"Process Implementation Functions">>}). +-doc(#{group => <<"Process Implementation Functions">>}). -callback system_continue(Parent, Debug, Misc) -> no_return() when Parent :: pid(), Debug :: [dbg_opt()], @@ -240,7 +237,7 @@ Called from `handle_system_msg/6` when the process is to continue its execution Called from `handle_system_msg/6` when the process is to return a term that reflects its current state. `State` is the value returned by `get_state/2`. """. --doc(#{title => <<"Process Implementation Functions">>, +-doc(#{group => <<"Process Implementation Functions">>, since => <<"OTP 17.0">>}). -callback system_get_state(Misc) -> {ok, State} when Misc :: term(), State :: term(). @@ -248,7 +245,7 @@ reflects its current state. `State` is the value returned by `get_state/2`. Called from `handle_system_msg/6` when the process is to replace its current state. `NState` is the value returned by `replace_state/3`. """. --doc(#{title => <<"Process Implementation Functions">>, +-doc(#{group => <<"Process Implementation Functions">>, since => <<"OTP 17.0">>}). -callback system_replace_state(StateFun, Misc) -> {ok, NState, NMisc} when Misc :: term(), @@ -261,7 +258,7 @@ this function is called when the process is suspended and its parent orders shutdown. It gives the process a chance to do a cleanup. This function never returns. """. --doc(#{title => <<"Process Implementation Functions">>}). +-doc(#{group => <<"Process Implementation Functions">>}). -callback system_terminate(Reason, Parent, Debug, Misc) -> no_return() when Reason :: term(), Parent :: pid(), @@ -814,7 +811,7 @@ Argument `Misc` can be used to save internal data in a process, for example, its state. It is sent to [`Module:system_continue/3`](`c:system_continue/3`) or [`Module:system_terminate/4`](`c:system_terminate/4`). """. --doc(#{title => <<"Process Implementation Functions">>}). +-doc(#{group => <<"Process Implementation Functions">>}). -spec handle_system_msg(Msg, From, Parent, Module, Debug, Misc) -> no_return() when Msg :: term(), @@ -856,7 +853,7 @@ to print the events, which is necessary if tracing is activated. `Extra` is any extra information that the process needs in the format function, for example, the process name. """. --doc(#{title => <<"Process Implementation Functions">>}). +-doc(#{group => <<"Process Implementation Functions">>}). -spec handle_debug(Debug, FormFunc, Extra, Event) -> [dbg_opt()] when Debug :: [dbg_opt()], FormFunc :: format_fun(), @@ -1114,7 +1111,7 @@ Gets the data associated with a debug option. `Default` is returned if `Item` is not found. Can be used by the process to retrieve debug data for printing before it terminates. """. --doc(#{title => <<"Process Implementation Functions">>}). +-doc(#{group => <<"Process Implementation Functions">>}). -spec get_debug(Item, Debug, Default) -> term() when Item :: 'log' | 'statistics', Debug :: [dbg_opt()], @@ -1133,7 +1130,7 @@ get_debug2(Item, Debug, Default) -> Prints the logged system events in the debug structure, using `FormFunc` as defined when the event was generated by a call to `handle_debug/4`. """. --doc(#{title => <<"Process Implementation Functions">>}). +-doc(#{group => <<"Process Implementation Functions">>}). -spec print_log(Debug) -> 'ok' when Debug :: [dbg_opt()]. print_log(Debug) -> @@ -1144,7 +1141,7 @@ print_log(Debug) -> Returns the logged system events in the debug structure, that is the last argument to `handle_debug/4`. """. --doc(#{title => <<"Process Implementation Functions">>, +-doc(#{group => <<"Process Implementation Functions">>, since => <<"OTP-22.0">>}). -spec get_log(Debug) -> [system_event()] when Debug :: [dbg_opt()]. @@ -1242,7 +1239,7 @@ Can be used by a process that initiates a debug structure from a list of options. The values of argument `Opt` are the same as for the corresponding functions. """. --doc(#{title => <<"Process Implementation Functions">>}). +-doc(#{group => <<"Process Implementation Functions">>}). -spec debug_options([Opt :: debug_option()]) -> [dbg_opt()]. debug_options(Options) -> debug_options(Options, []). diff --git a/lib/stdlib/src/zip.erl b/lib/stdlib/src/zip.erl index ef9afe8b24ae..a8050cff98c7 100644 --- a/lib/stdlib/src/zip.erl +++ b/lib/stdlib/src/zip.erl @@ -60,7 +60,6 @@ convention, add `.zip` to the filename. archive, the whole archive must be recreated. """. -define(ERL_TAR_COMPATIBILITY, ~"erl_tar compatibility functions"). --moduledoc(#{ titles => [{function, ?ERL_TAR_COMPATIBILITY}]}). -compile(nowarn_deprecated_catch). @@ -1083,7 +1082,7 @@ get_list_dir_options(F, Options) -> get_list_dir_opt(Options, Opts). %% aliases for erl_tar compatibility --doc #{ title => ?ERL_TAR_COMPATIBILITY }. +-doc(#{group => ?ERL_TAR_COMPATIBILITY }). -doc #{ equiv => list_dir(Archive, []) }. -spec(table(Archive) -> RetValue when Archive :: file:name() | binary(), @@ -1092,7 +1091,7 @@ get_list_dir_options(F, Options) -> table(F) -> list_dir(F). --doc #{ title => ?ERL_TAR_COMPATIBILITY }. +-doc(#{group => ?ERL_TAR_COMPATIBILITY }). -doc #{ equiv => list_dir(Archive, Options) }. -spec(table(Archive, Options) -> RetValue when Archive :: file:name() | binary(), @@ -1104,7 +1103,7 @@ table(F) -> list_dir(F). table(F, O) -> list_dir(F, O). --doc #{ title => ?ERL_TAR_COMPATIBILITY }. +-doc(#{group => ?ERL_TAR_COMPATIBILITY }). -doc(#{ equiv => zip(Name, FileList)} ). -spec(create(Name, FileList) -> RetValue when Name :: file:name(), @@ -1117,7 +1116,7 @@ table(F, O) -> list_dir(F, O). create(F, Fs) -> zip(F, Fs). --doc #{ title => ?ERL_TAR_COMPATIBILITY }. +-doc(#{group => ?ERL_TAR_COMPATIBILITY }). -doc(#{ equiv => zip(Name, FileList, Options) }). -spec(create(Name, FileList, Options) -> RetValue when Name :: file:name(), @@ -1131,7 +1130,7 @@ create(F, Fs) -> zip(F, Fs). | {error, Reason :: term()}). create(F, Fs, O) -> zip(F, Fs, O). --doc #{ title => ?ERL_TAR_COMPATIBILITY }. +-doc(#{group => ?ERL_TAR_COMPATIBILITY }). -doc(#{ equiv => unzip(Archive)} ). -spec(extract(Archive) -> RetValue when Archive :: file:name() | binary(), @@ -1144,7 +1143,7 @@ create(F, Fs, O) -> zip(F, Fs, O). extract(F) -> unzip(F). --doc #{ title => ?ERL_TAR_COMPATIBILITY }. +-doc(#{group => ?ERL_TAR_COMPATIBILITY }). -doc(#{ equiv => unzip(Archive, Options) }). -spec(extract(Archive, Options) -> RetValue when Archive :: file:name() | binary(), diff --git a/lib/stdlib/test/edlin_expand_SUITE.erl b/lib/stdlib/test/edlin_expand_SUITE.erl index 15abaaa7f07e..520745000438 100644 --- a/lib/stdlib/test/edlin_expand_SUITE.erl +++ b/lib/stdlib/test/edlin_expand_SUITE.erl @@ -85,16 +85,17 @@ normal(Config) when is_list(Config) -> {yes,"test:",[]} = do_expand("expand_"), {no, [], []} = do_expand("expandXX_"), {no,[],[#{ - title:="functions", + title:="Functions", elems:=[{"a_fun_name",[{ending,"("}]}, {"a_less_fun_name",_}, {"b_comes_after_a",_}, {"expand0arity_entirely",_}, {"module_info",_}] }]} = do_expand("expand_test:"), - {yes,[],[#{title:="functions", + {yes,[],[#{title:="Functions", elems:=[{"a_fun_name",_},{"a_less_fun_name",_}]}]} = do_expand("expand_test:a_"), {yes,"arity_entirely()",[]} = do_expand("expand_test:expand0"), + {no, [], [#{title:="Functions"}, #{title:="Obsolete API functions"}]} = do_expand("string:"), ok. to_atom(Str) -> @@ -524,7 +525,7 @@ get_coverage(Config) -> lists:flatten(edlin_expand:format_matches(M10, 20)), %% Test that we are not filtering duplicates bit with different case or different string lengths {yes,"e", M11} = do_expand("complete_function_parameter:cas"), - "\e[;1;4mfunctions\e[0m\ncaseSensitiveFunction( casesensitivefunction( \ncaseSensitiveFunctionName(\n" = do_format(M11), + "\e[;1;4mFunctions\e[0m\ncaseSensitiveFunction( casesensitivefunction( \ncaseSensitiveFunctionName(\n" = do_format(M11), ok. %% Normal module name, some function names using quoted atoms. @@ -534,7 +535,7 @@ quoted_fun(Config) when is_list(Config) -> %% should be no colon after test this time {yes, "test", [#{title:="modules", elems:=[{"expand_test",[{ending, ":"}]},{"expand_test1",_}]}]} = do_expand("expand_"), {no, [], []} = do_expand("expandXX_"), - {no,[],[#{title:="functions", + {no,[],[#{title:="Functions", elems:=[{"'#weird-fun-name'",_}, {"'Quoted_fun_name'",_}, {"'Quoted_fun_too'",_}, @@ -567,7 +568,7 @@ quoted_module(Config) when is_list(Config) -> {"a_less_fun_name",_}, {"b_comes_after_a",_}, {"module_info",_}]}]} = do_expand("'ExpandTestCaps':"), - {yes,[],[#{title:="functions", elems:=[{"a_fun_name",_}, + {yes,[],[#{title:="Functions", elems:=[{"a_fun_name",_}, {"a_less_fun_name",_}]}]} = do_expand("'ExpandTestCaps':a_"), ok. diff --git a/lib/tftp/src/tftp.erl b/lib/tftp/src/tftp.erl index fdbe527d7034..e28b07209cbc 100644 --- a/lib/tftp/src/tftp.erl +++ b/lib/tftp/src/tftp.erl @@ -26,13 +26,6 @@ %%% Created : 18 May 2004 by Hakan Mattsson %%%------------------------------------------------------------------- -module(tftp). - --moduledoc(#{titles => - [{function,<<"Client API">>}, - {function,<<"Server API">>} - ]} - ). - -moduledoc """ Trivial FTP. @@ -269,7 +262,7 @@ with new values in `AcceptedOptions`. """. --doc(#{title => <<"Client API">>, +-doc(#{group => <<"Client API">>, since => <<"OTP 18.1">>}). -callback open(Peer :: peer(), Access :: access(), @@ -323,7 +316,7 @@ However, it is invoked if the functions fail (crash). -doc(#{since => <<"OTP 18.1">>}). -callback abort(Code :: error_code(), string(), State :: term()) -> 'ok'. --doc(#{title => <<"Client API">>}). +-doc(#{group => <<"Client API">>}). -doc """ Reads a (virtual) file `RemoteFilename` from a TFTP server. @@ -354,7 +347,7 @@ read_file(RemoteFilename, LocalFilename, Options) -> tftp_engine:client_start(read, RemoteFilename, LocalFilename, Options). --doc(#{title => <<"Client API">>}). +-doc(#{group => <<"Client API">>}). -doc """ Writes a (virtual) file `RemoteFilename` to a TFTP server. @@ -384,7 +377,7 @@ matching regexp is found. write_file(RemoteFilename, LocalFilename, Options) -> tftp_engine:client_start(write, RemoteFilename, LocalFilename, Options). --doc(#{title => <<"Server API">>}). +-doc(#{group => <<"Server API">>}). -doc """ Starts a daemon process listening for UDP packets on a port. @@ -401,7 +394,7 @@ start(Options) -> tftp_engine:daemon_start(Options). --doc(#{title => <<"Server API">>}). +-doc(#{group => <<"Server API">>}). -doc """ Returns information about all TFTP server. """. @@ -409,7 +402,7 @@ info(Pid) -> tftp_engine:info(Pid). --doc(#{title => <<"Server API">>}). +-doc(#{group => <<"Server API">>}). -doc """ Changes configuration a TFTP Server """. diff --git a/lib/tools/src/lcnt.erl b/lib/tools/src/lcnt.erl index 840e7621ecde..f224bb4afda5 100644 --- a/lib/tools/src/lcnt.erl +++ b/lib/tools/src/lcnt.erl @@ -56,10 +56,7 @@ enables this behavior during profiling. [LCNT User's Guide](lcnt_chapter.md) """. --moduledoc(#{since => "OTP R13B04", - titles => - [{function,<<"Convenience functions">>}, - {function,<<"Internal runtime lock counter controllers">>}]}). +-moduledoc(#{since => "OTP R13B04"}). -behaviour(gen_server). -author("Björn-Egil Dahlberg"). @@ -220,7 +217,7 @@ Valid categories are: This list is subject to change at any time, as is the category any given lock belongs to. """. --doc(#{title => <<"Internal runtime lock counter controllers">>, +-doc(#{group => <<"Internal runtime lock counter controllers">>, since => <<"OTP 20.1">>}). -spec rt_mask(Node, Categories) -> 'ok' | {'error', 'copy_save_enabled'} when Node :: node(), @@ -243,7 +240,7 @@ call returns the current lock category mask for node `Arg`. If `Arg` is a list, this call is equivalent to [`rt_mask(node(), Arg)`](`rt_mask/2`). """. --doc(#{title => <<"Internal runtime lock counter controllers">>, +-doc(#{group => <<"Internal runtime lock counter controllers">>, since => <<"OTP 20.1">>}). -spec rt_mask(Node) -> [category_atom()] when Node :: node(); @@ -263,7 +260,7 @@ rt_mask(Categories) when is_list(Categories) -> -doc """ Return the current category mask for the current node. """. --doc(#{title => <<"Internal runtime lock counter controllers">>, +-doc(#{group => <<"Internal runtime lock counter controllers">>, since => <<"OTP 20.1">>}). -spec rt_mask() -> [category_atom()]. @@ -273,7 +270,7 @@ rt_mask() -> -type lock_counter_data() :: term(). -doc "Returns a list of raw lock counter data.". --doc(#{title => <<"Internal runtime lock counter controllers">>, +-doc(#{group => <<"Internal runtime lock counter controllers">>, since => <<"OTP R13B04">>}). -spec rt_collect(Node) -> [lock_counter_data()] when Node :: node(). @@ -282,7 +279,7 @@ rt_collect(Node) -> rpc:call(Node, lcnt, rt_collect, []). -doc #{equiv => rt_collect(node())}. --doc(#{title => <<"Internal runtime lock counter controllers">>, +-doc(#{group => <<"Internal runtime lock counter controllers">>, since => <<"OTP R13B04">>}). -spec rt_collect() -> [lock_counter_data()]. @@ -294,7 +291,7 @@ Clear the internal counters. Equivalent to [`lcnt:clear(Node)`](`clear/1`). """. --doc(#{title => <<"Internal runtime lock counter controllers">>, +-doc(#{group => <<"Internal runtime lock counter controllers">>, since => <<"OTP R13B04">>}). -spec rt_clear(Node) -> 'ok' when Node :: node(). @@ -303,7 +300,7 @@ rt_clear(Node) -> rpc:call(Node, lcnt, rt_clear, []). -doc #{equiv => rt_clear(node())}. --doc(#{title => <<"Internal runtime lock counter controllers">>, +-doc(#{group => <<"Internal runtime lock counter controllers">>, since => <<"OTP R13B04">>}). -spec rt_clear() -> 'ok'. @@ -330,7 +327,7 @@ Option description: `process` to the lock category mask; see `lcnt:rt_mask/2`. Default: `true` """. --doc(#{title => <<"Internal runtime lock counter controllers">>, +-doc(#{group => <<"Internal runtime lock counter controllers">>, since => <<"OTP R13B04">>}). -spec rt_opt(Node, Option) -> boolean() when Node :: node(), @@ -341,7 +338,7 @@ rt_opt(Node, Arg) -> rpc:call(Node, lcnt, rt_opt, [Arg]). -doc #{equiv => rt_opt(node(), {Type, Value})}. --doc(#{title => <<"Internal runtime lock counter controllers">>, +-doc(#{group => <<"Internal runtime lock counter controllers">>, since => <<"OTP R13B04">>}). -spec rt_opt(Option) -> boolean() when Option :: {Type, Value :: boolean()}, @@ -607,8 +604,8 @@ call(Msg) -> %% -------------------------------------------------------------------- %% -doc #{equiv => apply(fun() -> erlang:apply(Module, Function, Args) end)}. --doc #{title => <<"Convenience functions">>, - since => <<"OTP R13B04">>}. +-doc(#{group => <<"Convenience functions">>, + since => <<"OTP R13B04">>}). -spec apply(Module, Function, Args) -> term() when Module :: module(), Function :: atom(), @@ -620,8 +617,8 @@ apply(M, F, As) when is_atom(M), is_atom(F), is_list(As) -> end). -doc #{equiv => apply(Fun, [])}. --doc #{title => <<"Convenience functions">>, - since => <<"OTP R13B04">>}. +-doc(#{group => <<"Convenience functions">>, + since => <<"OTP R13B04">>}). -spec apply(Fun) -> term() when Fun :: fun(). @@ -643,7 +640,7 @@ its previous behavior. The result of the applied function is returned. > `true` for the duration of the call, which can quickly lead to running out of > memory. """. --doc(#{title => <<"Convenience functions">>,since => <<"OTP R13B04">>}). +-doc(#{group => <<"Convenience functions">>,since => <<"OTP R13B04">>}). -spec apply(Fun, Args) -> term() when Fun :: fun(), Args :: [term()]. @@ -665,7 +662,7 @@ all_conflicts(Sort) -> conflicts([{max_locks, none}, {thresholds, []},{combine,false}, {sort, Sort}, {reverse, true}]). -doc #{equiv => pid(node(), Id, Serial)}. --doc(#{title => <<"Convenience functions">>,since => <<"OTP R13B04">>}). +-doc(#{group => <<"Convenience functions">>,since => <<"OTP R13B04">>}). -spec pid(Id, Serial) -> pid() when Id :: integer(), Serial :: integer(). @@ -673,7 +670,7 @@ all_conflicts(Sort) -> pid(Id, Serial) -> pid(node(), Id, Serial). -doc "Creates a process id with creation 0.". --doc(#{title => <<"Convenience functions">>,since => <<"OTP R13B04">>}). +-doc(#{group => <<"Convenience functions">>,since => <<"OTP R13B04">>}). -spec pid(Node, Id, Serial) -> pid() when Node :: node(), Id :: integer(), @@ -686,14 +683,14 @@ pid(Node, Id, Serial) when is_atom(Node) -> binary_to_term(list_to_binary([Header, bytes16(L), String, bytes32(Id), bytes32(Serial),0])). -doc #{equiv => port(node(), Id)}. --doc(#{title => <<"Convenience functions">>,since => <<"OTP R13B04">>}). +-doc(#{group => <<"Convenience functions">>,since => <<"OTP R13B04">>}). -spec port(Id) -> port() when Id :: integer(). port(Id) -> port(node(), Id). -doc "Creates a port id with creation 0.". --doc(#{title => <<"Convenience functions">>,since => <<"OTP R13B04">>}). +-doc(#{group => <<"Convenience functions">>,since => <<"OTP R13B04">>}). -spec port(Node, Id) -> port() when Node :: node(), Id :: integer(). diff --git a/make/ex_doc.exs b/make/ex_doc.exs index 0bd98c140bdb..89f58b66ab39 100644 --- a/make/ex_doc.exs +++ b/make/ex_doc.exs @@ -76,7 +76,8 @@ titles = [], fn module, acc -> case Code.fetch_docs(module) do - {:docs_v1, _, :erlang, _, _, %{:titles => ts}, _} -> + {:docs_v1, _, :erlang, _, _, _, fun_docs} -> + ts = for {{type, _, _}, _, _, _, %{group: group}} <- fun_docs, do: {type, group} acc ++ ts _ -> @@ -88,31 +89,31 @@ titles = groups_for_docs = Enum.map( - Access.get(titles, :type, []), + Enum.sort(Access.get(titles, :type, [])), fn {:type, title} -> {"Types: #{title}", fn a -> - a[:kind] == :type && String.equivalent?(Access.get(a, :title, ""), title) + a[:kind] == :type && String.equivalent?(Access.get(a, :group, ""), title) end} end ) ++ [Types: &(&1[:kind] == :type)] ++ Enum.map( - Access.get(titles, :callback, []), + Enum.sort(Access.get(titles, :callback, [])), fn {:callback, title} -> {"Callbacks: #{title}", fn a -> - a[:kind] == :callback && String.equivalent?(Access.get(a, :title, ""), title) + a[:kind] == :callback && String.equivalent?(Access.get(a, :group, ""), title) end} end ) ++ [Callbacks: &(&1[:kind] == :callback)] ++ Enum.map( - Access.get(titles, :function, []), + Enum.sort(Access.get(titles, :function, [])), fn {:function, title} -> {"#{title}", fn a -> - a[:kind] == :function && String.equivalent?(Access.get(a, :title, ""), title) + a[:kind] == :function && String.equivalent?(Access.get(a, :group, ""), title) end} end )