EEP 65: -import_type directive

[ilya-klyuchnikov]

EEP: erlang/eep#51

[github-actions]

CT Test Results

       4 files     122 suites   55m 51s ⏱️
2 347 tests 2 295 ✔️ 52 💤 0 ❌
2 730 runs  2 675 ✔️ 55 💤 0 ❌

Results for commit 51889c6.

♻️ This comment has been updated with latest results.

To speed up review, make sure that you have read Contributing to Erlang/OTP and that all checks pass.

See the TESTING and DEVELOPMENT HowTo guides for details about how to run test locally.

Artifacts

• Complete CT logs (Download Logs)
• HTML Documentation (Download HTML Docs)
• Windows Installer

// Erlang/OTP Github Action Bot

[mikpe]

How is -import_type(m, [t/0]). different from -type t() :: m:t(). which works today?

[ilya-klyuchnikov]

How is -import_type(m, [t/0]). different from -type t() :: m:t(). which works today?

The EEP erlang/eep#51 provides the motivation.

Let me try to explain the motivation from the EEP using the example, assuming that the local type alias -type t() :: m:t(). is used with the intent of reducing boilerplate in specs (and probably other type aliases) in the module. Then the differences would be:

1. Clarity of the intent. -import_type(m, [t/0]). clearly communicates that the developer wants to use the type m:t() by its short name. The purpose of -type t() :: m:t(). may not be so clear. () What if it further evolves into -type t() :: m:t() | p:t() | z:t(). which can be encountered in large code bases. For example, in erl_lint the purpose is communicated through an additional comment:

   otp/lib/stdlib/src/erl_lint.erl

   Line 88 in 5bd165d

   -type anno() :: erl_anno:anno(). % a convenient alias

2. Code navigation and readability. Once -import_type is part of the language, - it's natural for tooling/IDE (Erlang LS, IntelliJ Erlang plugin, ...) to support it similar to how -import(m, [my_fun/0]) is supported now. So, with -import_type navigation from a usage t() would go directly to the definition of m:t() inside the module m, while with the local type alias navigation from a usage t() would go to the local type alias first. - Which creates an extra hop for someone reading, navigating and understanding the code.
3. Straightforward renaming/refactoring with tooling. Consider renaming m:t() inside the module m to something else - eg m:t1(). With import_type all the imported occurrences (in other modules) would be renamed. While for the local type alias the renaming would stop at -type t() :: m:t1().
4. Less boilerplate when referencing parameterized types. Consider -import_type(gb_trees, [tree/2]). vs -type tree(Key, Value) :: gb_trees:tree(Key, Value).

To summarize: the differences are mostly about consistency and ergonomics when working with code.

[kikofernandez]

you can expect some updates regarding this PR by the end of the week

[garazdawi]

There are a couple of tools that I think would need updating (or at least test cases added) before this PR is merged. A none-complete list is:

• edoc
• erl_docgen (possibly updating edoc is enough)
• syntax_tools
• emacs-mode?

Non-OTP tools that will also be effected (just listed here for reference):

• ErlangLS
• ELP
• ExDoc

[kikofernandez]

These are small nitpicks to consider.

I can review the PR again once the changes requested by @garazdawi have been addressed.

[ilya-klyuchnikov]

@kikofernandez - I have added edoc integration, - it works through keeping the mapping of imported types and using them in edoc_spec:d2e function. A simple test case has been added checking that an imported type in a spec is unfolded.

as @garazdawi mentioned - erl_docgen works then out of the box, - I have tested it with the string module - that extensively uses unicode:chardata() type: importing it as -import_type(unicode,[chardata/0]). and replacing all the references unicode:chardata() -> unicode:chardata(). The generated documentation contains unfolded unicode:chardata() in specs.

[ilya-klyuchnikov]

I am not sure what to do about the following items:

• syntax_tools
• emacs-mode
• edoc chunks (EEP 48)

Any advice would be much appreciated!

[garazdawi]

I am not sure what to do about the following items:

• syntax_tools

I would expect erl_syntax, erl_syntax_lib and prettypr to need functionality similar to what they have for import.

• emacs-mode

Check that the syntax highlighting and flymake works the same for import_type as import.

• edoc chunks (EEP 48)

It may just work with your updates in edoc. Add a testcase to the eep48_SUITE that checks that an imported type behaves the same as a remote type.