Skip to content

Commit

Permalink
Merge pull request #9408 from frazze-jobb/frazze/stdlib/support_eep48…
Browse files Browse the repository at this point in the history 
…_group_metadata/OTP-19483

Use eep48 "group" to group functions in OTP documentation and shell completion
OTP-19483
  • Loading branch information
@frazze-jobb
frazze-jobb authored Feb 25, 2025
2 parents b45ce1e + 8c71b97 commit 4929103
Show file tree
Hide file tree
Showing 41 changed files with 1,095 additions and 1,242 deletions.
13 changes: 4 additions & 9 deletions HOWTO/DOCUMENTATION.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
```

Expand Down
39 changes: 19 additions & 20 deletions erts/preloaded/src/erl_tracer.erl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]).

Expand Down Expand Up @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand Down
41 changes: 20 additions & 21 deletions lib/common_test/src/ct_hooks.erl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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]).
Expand Down Expand Up @@ -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 """
Expand All @@ -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(),
Expand Down Expand Up @@ -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 |
Expand Down Expand Up @@ -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 |
Expand All @@ -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}],
Expand All @@ -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,
Expand All @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand Down Expand Up @@ -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(),
Expand All @@ -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(),
Expand Down Expand Up @@ -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(),
Expand All @@ -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(),
Expand All @@ -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(),
Expand Down Expand Up @@ -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}],
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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},
Expand Down Expand Up @@ -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],
Expand Down Expand Up @@ -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(
Expand Down
Loading

0 comments on commit 4929103

Please sign in to comment.