Sign Up
Log In
Log In
or
Sign Up
Places
All Projects
Status Monitor
Collapse sidebar
home:Ledest:erlang:23
erlang
0237-otp-Document-previously-removed-functions....
Overview
Repositories
Revisions
Requests
Users
Attributes
Meta
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
Locations
Projects
Search
Status Monitor
Help
OpenBuildService.org
Documentation
API Documentation
Code of Conduct
Contact
Support
@OBShq
Terms
openSUSE Build Service is sponsored by
The Open Build Service is an
openSUSE project
.
Sign Up
Log In
Places
Places
All Projects
Status Monitor
