Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Use eep48 "group" to group functions in OTP documentation and shell completion #9408

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
+1,108 −1,245
Open

Use eep48 "group" to group functions in OTP documentation and shell completion #9408

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a963abe
docs: replace title with group, remove titles and redundant groups
frazze-jobb Feb 5, 2025
631e28b
docs: change group_for_docs in ex_doc.exs, to use :group metadata
frazze-jobb Feb 5, 2025
8c187a8
stdlib: update edlin_expand to group functions based on eep48 group
frazze-jobb Feb 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 4 additions & 9 deletions HOWTO/DOCUMENTATION.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Loading