File 0872-Apply-suggestions-from-elbrujohalcon-review.patch of Package erlang
From 643572e3e1ef6da526afd4e0b3be35a7ef48389a Mon Sep 17 00:00:00 2001
From: Max Heiber <max.heiber@gmail.com>
Date: Mon, 20 Dec 2021 21:18:18 +0000
Subject: [PATCH 2/3] Apply suggestions from elbrujohalcon review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Co-authored-by: Brujo Benavides <elbrujohalcon@gmail.com>
Co-authored-by: John Högberg <john@erlang.org>
---
system/doc/reference_manual/opaques.xml | 46 ++++++++++++-------------
system/doc/reference_manual/part.xml | 1 +
system/doc/reference_manual/xmlfiles.mk | 3 +-
3 files changed, 25 insertions(+), 25 deletions(-)
diff --git a/system/doc/reference_manual/opaques.xml b/system/doc/reference_manual/opaques.xml
index 1514ab01cb..b14042cb19 100644
--- a/system/doc/reference_manual/opaques.xml
+++ b/system/doc/reference_manual/opaques.xml
@@ -22,7 +22,7 @@
</legalnotice>
- <title>Types and Function Specifications</title>
+ <title>Opaques</title>
<prepared>Max Heiber</prepared>
<docno></docno>
<date></date>
@@ -30,40 +30,38 @@
<file>opaques.xml</file>
</header>
- <section>
- <title>Opaque Type Aliases</title>
- <p>The main use case for opacity in Erlang is to hide the implementation of a data type, enabling evolving the API while minimizing risk of breaking consumers. The runtime does not check opacity. Dialyzer provides some opacit-checking, but the rest is up to convention.
+ <section><title>Opaque Type Aliases</title>
+ <p>The main use case for opacity in Erlang is to hide the implementation of a data type, enabling evolving the API while minimizing the risk of breaking consumers. The runtime does not check opacity. Dialyzer provides some opacity-checking, but the rest is up to convention.
</p>
<p>
-This document explains what Erlang opacity is (and the trade-offs involved) via the example of OTP's `sets:set()` data type. This type *was* defined in `sets` module like this:
+This document explains what Erlang opacity is (and the trade-offs involved) via the example of OTP's <c>sets:set()</c> data type. This type <em>was</em> defined in `sets` module like this:
</p>
-
- <pre>-opaque set(Element) :: #set{segs :: segs(Element)}.</pre>
- OTP 24 changed the definition to the following, in <a href="https://github.com/erlang/otp/commit/e66941e8d7c47b973dff94c0308ea85a6be1958e">this commit</a>.
- <pre>-opaque set(Element) :: #set{segs :: segs(Element)} | #{Element => ?VALUE}.</pre>
-<p>And this change was safer and more backwards-compatible than if the type had been defined with <pre>-type</pre> instead of <pre>-opaque</pre>. Here's why: when a module defines an <pre>-opaque</pre>, the contract is that only the defining module should rely on the definition of the type: no other modules should rely on the definition.</p>
-<p>This means that code that pattern-matched on <pre>set</pre> as a record/tuple technically broke the contract, and opted in to being potentially broken when the definition of <pre>set()</pre> changed. Before OTP 24, this code printed <pre>ok</pre>. In OTP 24 it may error:</p>
- <pre>
- Set = sets:new(),
-caseof
- X when is_tuple(Set) ->
+ <p>
+ <code type="erl">-opaque set(Element) :: #set{segs :: segs(Element)}.</code>
+ OTP 24 changed the definition to the following, in <url href="https://github.com/erlang/otp/commit/e66941e8d7c47b973dff94c0308ea85a6be1958e">this commit</url>.
+ <code type="erl">-opaque set(Element) :: #set{segs :: segs(Element)} | #{Element => ?VALUE}.</code>
+<p>And this change was safer and more backwards-compatible than if the type had been defined with <c>-type</c> instead of <c>-opaque</c>. Here's why: when a module defines an <c>-opaque</c>, the contract is that only the defining module should rely on the definition of the type: no other modules should rely on the definition.</p>
+<p>This means that code that pattern-matched on <c>set</c> as a record/tuple technically broke the contract, and opted in to being potentially broken when the definition of <c>set()</c> changed. Before OTP 24, this code printed <c>ok</c>. In OTP 24 it may error:</p>
+ <code type="erl">
+case sets:new() of
+ Set when is_tuple(Set) ->
io:format("ok")
end.
- </pre>
+ </code>
+</p>
<p><strong>When working with an opaque defined in another module, here are some recommendations:</strong></p>
<list type="bulleted">
-<item>Don't examine the underlying type using pattern-matching, guards, or functions that reveal the type, such as <pre>tuple_size/1</pre>.</item>
-<item>Instead, use functions provided by the module for working with the type. For example, <pre>sets</pre> module provides <pre>sets:new/0</pre>, <pre>sets:add/2</pre>, <pre>sets:is_element/2</pre>, etc.</item>
-<item><pre>sets:set(a)</pre> is a subtype of <pre>sets:set(a | b)</pre> and not the other way around. Generally, you can rely on the property that <pre>the_opaque(T)</pre> is a subtype of <pre>the_opaque(U)</pre> when T is a subtype of U.</item>
+<item>Don't examine the underlying type using pattern-matching, guards, or functions that reveal the type, such as <c>tuple_size/1</c>.</item>
+<item>Instead, use functions provided by the module for working with the type. For example, <c>sets</c> module provides <c>sets:new/0</c>, <c>sets:add/2</c>, <c>sets:is_element/2</c>, etc.</item>
+<item><c>sets:set(a)</c> is a subtype of <c>sets:set(a | b)</c> and not the other way around. Generally, you can rely on the property that <c>the_opaque(T)</c> is a subtype of <c>the_opaque(U)</c> when T is a subtype of U.</item>
</list>
<p><strong>When defining your own opaques, here are some recommendations:</strong></p>
<list type="bulleted">
-<item>Since consumers are expected to not rely on the definition of the opaque type, you must provide functions for constructing and querying/deconstructing intances of your opaque type. For example, sets can be constructed with <pre>sets:new/0</pre>, <pre>sets:from_list/1</pre>, <pre>sets:add/2</pre>, queried with <pre>sets:is_element/2</pre>, and deconstructed with <pre>sets:to_list/1</pre>.</item>
-<item>Don't define an opaque with a type variable in parameter position. This breaks the normal and expected behavior that (for example) <pre>my_type(a)</pre> is a subtype of <pre>my_type(a | b)</pre></item>
+<item>Since consumers are expected to not rely on the definition of the opaque type, you must provide functions for constructing and querying/deconstructing intances of your opaque type. For example, sets can be constructed with <c>sets:new/0</c>, <c>sets:from_list/1</c>, <c>sets:add/2</c>, queried with <c>sets:is_element/2</c>, and deconstructed with <c>sets:to_list/1</c>.</item>
+<item>Don't define an opaque with a type variable in parameter position. This breaks the normal and expected behavior that (for example) <c>my_type(a)</c> is a subtype of <c>my_type(a | b)</c></item>
+<item>Add <seeguide marker="typespec">specs</seeguide> to exported functions that use the opaque type</item>
</list>
<p>Note that opaques can be harder to work with for consumers, since the consumer is expected not to pattern-match and must instead use functions that the author of the opaque type provides to use instances of the type.</p>
-<p>Also, opacity in Erlang is skin-deep: the runtime does not enforce opacity-checking. So now that sets are implemented in terms of maps, an <pre>is_map</pre> check on a set <em>will</em> pass. The opacity rules are only enforced by convention and by additional tooling such as Dialyzer. And this enforcement is not total: For example, determined consumer of <pre>sets</pre> can still do things that reveal the structure of the set, such as by printing, serializing, or using a set as <pre>term()</pre> and then inspecting via functions like <pre>is_map</pre> or <pre>maps:get/2</pre>. And Dialyzer must make some <a href="https://github.com/erlang/otp/issues/5118">approximations</a>. Opacity checking has limitations, but is still a vital tool in scalable Erlang development.</p>
-
- </section>
+<p>Also, opacity in Erlang is skin-deep: the runtime does not enforce opacity-checking. So now that sets are implemented in terms of maps, an <c>is_map</c> check on a set <em>will</em> pass. The opacity rules are only enforced by convention and by additional tooling such as Dialyzer. And this enforcement is not total: For example, determined consumer of <c>sets</c> can still do things that reveal the structure of the set, such as by printing, serializing, or using a set as <c>term()</c> and then inspecting via functions like <c>is_map</c> or <c>maps:get/2</c>. And Dialyzer must make some <url href="https://github.com/erlang/otp/issues/5118">approximations</url>. Opacity checking has limitations, but is still a vital tool in scalable Erlang development.</p></section>
</chapter>
diff --git a/system/doc/reference_manual/part.xml b/system/doc/reference_manual/part.xml
index 3d31157973..8563861069 100644
--- a/system/doc/reference_manual/part.xml
+++ b/system/doc/reference_manual/part.xml
@@ -35,6 +35,7 @@
<xi:include href="modules.xml"/>
<xi:include href="functions.xml"/>
<xi:include href="typespec.xml"/>
+ <xi:include href="opaques.xml"/>
<xi:include href="expressions.xml"/>
<xi:include href="macros.xml"/>
<xi:include href="records.xml"/>
diff --git a/system/doc/reference_manual/xmlfiles.mk b/system/doc/reference_manual/xmlfiles.mk
index 92d232b628..687eeea4c8 100644
--- a/system/doc/reference_manual/xmlfiles.mk
+++ b/system/doc/reference_manual/xmlfiles.mk
@@ -32,4 +32,5 @@ REF_MAN_CHAPTER_FILES = \
code_loading.xml \
ports.xml \
character_set.xml \
- typespec.xml
+ typespec.xml \
+ opaques.xml
--
2.31.1
