1 files changed, 28 insertions, 23 deletions
diff --git a/lib/stdlib/test/shell_docs_SUITE_data/unknown_erlang_unlink_1_func.txt b/lib/stdlib/test/shell_docs_SUITE_data/unknown_erlang_unlink_1_func.txt
index 23fecba59c..9668d64fe3 100644
--- a/lib/stdlib/test/shell_docs_SUITE_data/unknown_erlang_unlink_1_func.txt
+++ b/lib/stdlib/test/shell_docs_SUITE_data/unknown_erlang_unlink_1_func.txt
@@ -1,23 +1,31 @@
 
   [;1m-spec unlink(Id) -> true when Id :: pid() | port().[0m
 
-  Removes the link, if there is one, between the calling process and
-  the process or port referred to by [;;4mId[0m.
+  Removes a link between the calling process and another process or
+  a port identified by [;;4mId[0m. We will from here on call the
+  identified process or port unlinkee.
 
-  Returns [;;4mtrue[0m and does not fail, even if there is no link to [;;4mId[0m,
-  or if [;;4mId[0m does not exist.
+  A link can be set up using the [;;4mlink/1[0m BIF. For more information
+  on links and exit signals due to links, see the Processes
+  chapter in the Erlang Reference Manual:
 
-  Once [;;4munlink(Id)[0m has returned, it is guaranteed that the link
-  between the caller and the entity referred to by [;;4mId[0m has no
-  effect on the caller in the future (unless the link is setup
-  again). If the caller is trapping exits, an [;;4m{'EXIT', Id, _}[0m
-  message from the link can have been placed in the caller's message
-  queue before the call.
+   • Links
+
+   • Sending Exit Signals
 
-  Notice that the [;;4m{'EXIT', Id, _}[0m message can be the result of the
-  link, but can also be the result of [;;4mId[0m calling [;;4mexit/2[0m.
-  Therefore, it can be appropriate to clean up the message queue
-  when trapping exits after the call to [;;4munlink(Id)[0m, as follows:
+   • Receiving Exit Signals
+
+  Once [;;4munlink(Id)[0m has returned, it is guaranteed that the link
+  between the caller and the unlinkee has no effect on the caller in
+  the future (unless the link is setup again). Note that if the
+  caller is trapping exits, an [;;4m{'EXIT', Id, ExitReason}[0m message
+  due to the link may have been placed in the message queue of the
+  caller before the [;;4munlink(Id)[0m call completed. Also note that the [;;4m[0m
+  [;;4m{'EXIT', Id, ExitReason}[0m message may be the result of the link,
+  but may also be the result of the unlikee sending the caller an
+  exit signal by calling the [;;4mexit/2[0m BIF. Therefore, it may or may
+  not be appropriate to clean up the message queue after a call to [;;4m[0m
+  [;;4munlink(Id)[0m as follows, when trapping exits:
 
     unlink(Id),
     receive
@@ -27,13 +35,10 @@
             true
     end
 
-  Note:
-    Before Erlang/OTP R11B (ERTS 5.5) [;;4munlink/1[0m behaved
-    completely asynchronously, that is, the link was active until
-    the "unlink signal" reached the linked entity. This had an
-    undesirable effect, as you could never know when you were
-    guaranteed not to be effected by the link.
+  The link removal is performed asynchronously. If such a link does
+  not exist, nothing is done. A detailed description of the link
+  protocol can be found in the Distribution Protocol chapter of
+  the ERTS User's Guide.
 
-    The current behavior can be viewed as two combined operations:
-    asynchronously send an "unlink signal" to the linked entity
-    and ignore any future results of the link.
+  Failure: [;;4mbadarg[0m if [;;4mId[0m does not identify a process or a node
+  local port.