File 0237-otp-Document-previously-removed-functions.patch of Package erlang
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
