File 0237-otp-Document-previously-removed-functions.... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 0237-otp-Document-previously-removed-functions.patch of Package erlang (Revision 9c6f14cb59b6cc96e9e5afb6eccb708c)

Currently displaying revision 9c6f14cb59b6cc96e9e5afb6eccb708c , Show latest

From bc2d571d71edaa394a626e458adafde510900453 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?John=20H=C3=B6gberg?= <john@erlang.org>
Date: Mon, 18 Jan 2021 16:31:27 +0100
Subject: [PATCH] otp: Document previously removed functions

This commit adds a page for Removed Functionality in the user's
guide, listing the functions we've removed recently and still
warn about.
---
 HOWTO/DEPRECATE.md                       |  8 +-
 lib/stdlib/scripts/update_deprecations   | 99 ++++++++++++++----------
 system/doc/general_info/DEPRECATIONS     | 46 +++++++++++
 system/doc/general_info/Makefile         |  4 +-
 system/doc/general_info/part.xml         |  1 +
 system/doc/general_info/removed_head.inc | 39 ++++++++++
 system/doc/general_info/xmlfiles.mk      |  1 +
 7 files changed, 153 insertions(+), 45 deletions(-)
 create mode 100644 system/doc/general_info/removed_head.inc

diff --git a/HOWTO/DEPRECATE.md b/HOWTO/DEPRECATE.md
index a33b555e89..e292ca4c76 100644
--- a/HOWTO/DEPRECATE.md
+++ b/HOWTO/DEPRECATE.md
@@ -62,8 +62,9 @@ about their use.
 The [$ERL_TOP/system/doc/general_info/DEPRECATIONS][1] file contains additional
 information about each deprecated function, namely in what release it was deprecated
 and optionally in what release it will be removed. The information in this file will
-be used to generate the [Deprecations](http://erlang.org/doc/general_info/deprecations.html)
-and [Scheduled for Removal](http://erlang.org/doc/general_info/scheduled_for_removal.html)
+be used to generate the [Deprecations](http://erlang.org/doc/general_info/deprecations.html),
+[Scheduled for Removal](http://erlang.org/doc/general_info/scheduled_for_removal.html),
+and [Removed Functionality](http://erlang.org/doc/general_info/removed.html),
 pages in the documentation.
 
 Here is how the entry for `erlang:now/0` that was deprecated in OTP 18 looks like:
@@ -74,6 +75,9 @@ Here is an example of a function that was deprecated in OTP 23 and is scheduled
 
     filename:safe_relative_path/1 since=23 remove=25
 
+After removing a function it's important to keep its line in the DEPRECATIONS
+file for as long as we wish to raise warnings about it. Should a removal be
+postponed, the corresponding `remove` attribute must be bumped accordingly.
 
  [1]: ../system/doc/general_info/DEPRECATIONS
  [2]: ../lib/stdlib/src/otp_internal.erl
diff --git a/lib/stdlib/scripts/update_deprecations b/lib/stdlib/scripts/update_deprecations
index 47723ca4bc..013ef33991 100755
--- a/lib/stdlib/scripts/update_deprecations
+++ b/lib/stdlib/scripts/update_deprecations
@@ -201,48 +201,62 @@ insert_removals([], _Depr) ->
 make_xml(Top, Type, OutFile, InfoText0) ->
     DeprecationFile = deprecation_file(Top),
     OutDir = filename:dirname(DeprecationFile),
-    InfoTextMap = maps:from_list(make_xml_info(InfoText0)),
     Depr0 = read_deprecations(DeprecationFile),
     Depr = maps:to_list(Depr0),
-    {Key,Prefix} = case Type of
-                       "deprecations" ->
-                           {since,"deprecations"};
-                       "removals" ->
-                           {remove,"scheduled_for_removal"}
-                   end,
-    Collected = make_xml_collect(Depr, Key, InfoTextMap, []),
-    All = make_xml_gen(lists:reverse(Collected), Type, Prefix, OutDir),
+
+    {RelKey, AttrTag} =
+        case Type of
+            "deprecations" ->
+                %% Group by 'since' in DEPRECATIONS, grab text from
+                %% 'deprecated' attributes.
+                {since, deprecated};
+            "scheduled_for_removal" ->
+                {remove, deprecated};
+            "removed" ->
+                {remove, removed}
+        end,
+
+    InfoTextMap = maps:from_list(make_xml_info(InfoText0, AttrTag)),
+    Collected = make_xml_collect(Depr, RelKey, InfoTextMap, []),
+
+    All = make_xml_gen(lists:reverse(Collected), Type, OutDir),
     file:write_file(OutFile, All),
+
     ok.
 
-make_xml_info([{deprecated,M,F,A,Text}|T]) ->
-    [{{M,F,A},Text}|make_xml_info(T)];
-make_xml_info([{removed,_,_,_,_}|T]) ->
-    make_xml_info(T);
-make_xml_info([]) ->
+make_xml_info([{Tag,M,F,A,Text} | Attributes], Tag) ->
+    [{{M,F,A}, Text} | make_xml_info(Attributes, Tag)];
+make_xml_info([_ | Attributes], Tag) ->
+    make_xml_info(Attributes, Tag);
+make_xml_info([], _Tag) ->
     [].
 
-make_xml_collect([{MFA,Ps}|T], Key, InfoTextMap, Acc) ->
-    case lists:keyfind(Key, 1, Ps) of
-        {Key,Rel} ->
-            InfoText = case InfoTextMap of
-                           #{MFA := Text} -> Text;
-                           #{} -> []
-                       end,
-            make_xml_collect(T, Key, InfoTextMap, [{Rel,{MFA,InfoText}}|Acc]);
-        false ->
-            make_xml_collect(T, Key, InfoTextMap, Acc)
-    end;
-make_xml_collect([], _Key, _InfoTextMap, Acc) ->
+%% Joins `DEPRECATIONS` with module attributes, grabbing the text from said
+%% attributes and grouping them by the release version pointed out by `RelKey`
+%% ('since' or 'remove').
+make_xml_collect([{MFA, Ps} | T], RelKey, InfoTextMap, Acc0) ->
+    Acc = case lists:keyfind(RelKey, 1, Ps) of
+              {RelKey, Rel} ->
+                  case InfoTextMap of
+                      #{ MFA := Text } ->
+                          [{Rel, {MFA,Text}} | Acc0];
+                      #{} ->
+                          Acc0
+                  end;
+              false ->
+                  Acc0
+          end,
+    make_xml_collect(T, RelKey, InfoTextMap, Acc);
+make_xml_collect([], _RelKey, _InfoTextMap, Acc) ->
     rel2fam(Acc).
 
-make_xml_gen(Collected, Type, Prefix, Dir) ->
-    Head = get_xml_template(Dir, Prefix, head),
-    Contents = make_xml_gen_list(Collected, Type, Prefix, Dir),
+make_xml_gen(Collected, Type, Dir) ->
+    Head = get_xml_template(Dir, Type, head),
+    Contents = make_xml_gen_list(Collected, Type, Dir),
     Footer = "</chapter>\n",
     [Head,Contents,Footer].
 
-make_xml_gen_list([{Rel,MFAs}|T], Type, Prefix, Dir) ->
+make_xml_gen_list([{Rel,MFAs}|T], Type, Dir) ->
     RelStr = lists:concat(["OTP ",Rel]),
     RelMarker = lists:concat(["otp-",Rel]),
     Head = ["<section>\n",
@@ -252,16 +266,18 @@ make_xml_gen_list([{Rel,MFAs}|T], Type, Prefix, Dir) ->
     SubTitle = case Type of
                    "deprecations" ->
                        ["Functions Deprecated in ",RelStr];
-                   "removals" ->
-                       ["Functions Scheduled for Removal in ",RelStr]
+                   "scheduled_for_removal" ->
+                       ["Functions Scheduled for Removal in ",RelStr];
+                   "removed" ->
+                       ["Functions Removed in ",RelStr]
                end,
     SubHead = ["<section>\n",
                "<title>",SubTitle,"</title>\n"],
     SubFooter = "</section>\n",
-    [Head, get_xml_template(Dir, Prefix, Rel),
+    [Head, get_xml_template(Dir, Type, Rel),
      SubHead, make_xml_gen_mfas(MFAs), SubFooter,
-     Footer | make_xml_gen_list(T, Type, Prefix, Dir)];
-make_xml_gen_list([], _, _, _) ->
+     Footer | make_xml_gen_list(T, Type, Dir)];
+make_xml_gen_list([], _, _) ->
     [].
 
 make_xml_gen_mfas(MFAs) ->
@@ -295,10 +311,11 @@ check_deprecations(Top, #st{functions = Fs} = St) ->
         [] ->
             St#st{deprecations = Depr};
         [_|_] ->
-            Msg = "The following function(s) have -deprecated() attributes, "
-                "but are not present in the DEPRECATIONS file:\n\n",
+            Msg = "The following function(s) have -deprecated() or "
+                "-removed() attributes, but are not present in the "
+                "DEPRECATIONS file:\n\n",
             Bad = [io_lib:format("  ~w:~w/~w\n", [M,F,A]) ||
-                      {deprecated,M,F,A,_} <- Bad0],
+                      {_,M,F,A,_} <- Bad0],
             Loc = ["\n","Please update ",DeprFile,".\n"],
             io:put_chars(standard_error, [Msg,Bad,Loc]),
             halt(1)
@@ -312,10 +329,8 @@ read_deprecations(File) ->
 deprecation_file(Root) ->
     filename:join(Root, "system/doc/general_info/DEPRECATIONS").
 
-in_deprecations({deprecated,M,F,A,_}, Depr) ->
-    is_map_key({M,F,A}, Depr);
-in_deprecations({removed,_,_,_,_}, _Depr) ->
-    true.
+in_deprecations({Tag,M,F,A,_}, Depr) when Tag =:= deprecated; Tag =:= removed ->
+    is_map_key({M,F,A}, Depr).
 
 parse_deprecations([<<"#",_/binary>>|Lines]) ->
     parse_deprecations(Lines);
diff --git a/system/doc/general_info/DEPRECATIONS b/system/doc/general_info/DEPRECATIONS
index ccbe94bf5b..0b18d6216f 100644
--- a/system/doc/general_info/DEPRECATIONS
+++ b/system/doc/general_info/DEPRECATIONS
@@ -134,6 +135,7 @@ sys:get_debug/3 since=22
 # Added in OTP 21.
 #
 
+erlang:get_stacktrace/0 since=21 remove=23
 ssl:ssl_accept/_ since=21 remove=24
 
 #
@@ -157,8 +159,41 @@ random:_/_ since=19
 # Added in OTP 18.
 #
 
+core_lib:literal_value/1 since=18 remove=19
+core_lib:is_literal_list/1 since=18 remove=19
+core_lib:is_literal/1 since=18 remove=19
+core_lib:set_anno/2 since=18 remove=19
+core_lib:get_anno/1 since=18 remove=19
+
 erlang:now/0 since=18
 
+erl_lint:modify_line/2 since=18 remove=19
+
+erl_parse:get_attribute/2 since=18 remove=19
+erl_parse:get_attributes/1 since=18 remove=19
+erl_parse:set_line/2 since=18 remove=19
+
+erl_scan:token_info/_ since=18 remove=19
+erl_scan:attributes_info/_ since=18 remove=19
+erl_scan:set_attribute/3 since=18 remove=19
+
+ssl:connection_info/1 since=18 remove=20
+ssl:negotiated_next_protocol/1 since=18 remove=20
+
+httpd_conf:make_integer/1 since=18 remove=23
+httpd_conf:is_file/1 since=18 remove=23
+httpd_conf:is_directory/1 since=18 remove=23
+httpd_conf:custom_clean/3 since=18 remove=23
+httpd_conf:clean/1 since=18 remove=23
+httpd_conf:check_enum/2 since=18 remove=23
+
+#
+# Added in OTP 17.
+#
+
+asn1ct:encode/_ since=17 remove=20
+asn1ct:decode/_ since=17 remove=20
+
 #
 # Added in OTP 16.
 #
@@ -184,6 +219,14 @@ wxPostScriptDC:setResolution/1 since=16
 wxCursor:new/3 since=16
 wxCursor:new/4 since=16
 
+#
+# Added in OTP R13B03 or earlier. We don't know exactly when these were
+# deprecated.
+#
+
+os_mon_mib:_/_ since=13 remove=22
+erlang:hash/2 since=13 remove=20
+
 #
 # Added in OTP 12.
 #
@@ -195,6 +238,9 @@ auth:node_cookie/_ since=12
 
 calendar:local_time_to_universal_time/1 since=12
 
+rpc:safe_multi_server_call/3 since=12 remove=19
+rpc:safe_multi_server_call/2 since=12 remove=19
+
 #
 # Added in OTP 10.
 #
diff --git a/system/doc/general_info/Makefile b/system/doc/general_info/Makefile
index 5f087e22be..f7e1a86c5a 100644
--- a/system/doc/general_info/Makefile
+++ b/system/doc/general_info/Makefile
@@ -89,8 +89,10 @@ $(XMLDIR)/deprecations.xml: DEPRECATIONS
 	$(gen_verbose)escript $(DEPRECATIONS_SCRIPT) make_xml deprecations $(ERL_TOP) $@
 
 $(XMLDIR)/scheduled_for_removal.xml: DEPRECATIONS
-	$(gen_verbose)escript $(DEPRECATIONS_SCRIPT) make_xml removals $(ERL_TOP) $@
+	$(gen_verbose)escript $(DEPRECATIONS_SCRIPT) make_xml scheduled_for_removal $(ERL_TOP) $@
 
+$(XMLDIR)/removed.xml: DEPRECATIONS
+	$(gen_verbose)escript $(DEPRECATIONS_SCRIPT) make_xml removed $(ERL_TOP) $@
 
 clean clean_docs:
 	rm -f $(XMLDIR)/*.xml
diff --git a/system/doc/general_info/part.xml b/system/doc/general_info/part.xml
index fead7d58e7..f0f9194a47 100644
--- a/system/doc/general_info/part.xml
+++ b/system/doc/general_info/part.xml
@@ -30,5 +30,6 @@
     <file>part.xml</file>
   </header>
   <xi:include href="deprecations.xml"/>
+  <xi:include href="removed.xml"/>
   <xi:include href="scheduled_for_removal.xml"/>
 </part>
diff --git a/system/doc/general_info/removed_head.inc b/system/doc/general_info/removed_head.inc
new file mode 100644
index 0000000000..1e87e87a74
--- /dev/null
+++ b/system/doc/general_info/removed_head.inc
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2021</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.
+
+    </legalnotice>
+
+    <title>Removed Functionality</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+    <file>removed.xml</file>
+  </header>
+  <section>
+    <title>Introduction</title>
+    <p>This document lists all removed functionality in
+    Erlang/OTP. For more information regarding the strategy regarding
+    removals see the documentation of <seeguide
+    marker="system/system_principles:misc#removal">Support,
+    Compatibility, Deprecations, and Removal</seeguide>.</p>
+  </section>
diff --git a/system/doc/general_info/xmlfiles.mk b/system/doc/general_info/xmlfiles.mk
index c52930c62d..ebd69cafda 100644
--- a/system/doc/general_info/xmlfiles.mk
+++ b/system/doc/general_info/xmlfiles.mk
@@ -22,4 +22,5 @@ GENERAL_INFO_CHAPTER_FILES =
 
 GENERAL_INFO_CHAPTER_GEN_FILES = \
 	deprecations.xml \
+	removed.xml \
 	scheduled_for_removal.xml
-- 
2.26.2

Places

File 0237-otp-Document-previously-removed-functions.patch of Package erlang (Revision 9c6f14cb59b6cc96e9e5afb6eccb708c)

Places