Sign Up
Log In
Log In
or
Sign Up
Places
All Projects
Status Monitor
Collapse sidebar
home:Ledest:erlang:24
erlang
2431-doc-Improve-documentation-regarding-is_-ty...
Overview
Repositories
Revisions
Requests
Users
Attributes
Meta
File 2431-doc-Improve-documentation-regarding-is_-type-1-funct.patch of Package erlang
From b44d52b6217d436f6d721931ba5ccfa30dd5f3af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cons=20T=20=C3=85hs?= <cons@erlang.org> Date: Fri, 8 Apr 2022 11:51:11 +0200 Subject: [PATCH] [doc] Improve documentation regarding is_<type>/1 functions in libs * These functions can return a false positive result * Add some general wording regarding composite types and the non existence of user defined types --- lib/stdlib/doc/src/gb_sets.xml | 22 +++++++++--- lib/stdlib/doc/src/ordsets.xml | 6 ++-- lib/stdlib/doc/src/queue.xml | 21 ++++++++---- lib/stdlib/doc/src/sets.xml | 24 ++++++++++--- lib/stdlib/doc/src/sofs.xml | 39 ++++++++++++++++------ system/doc/reference_manual/data_types.xml | 12 +++++-- 6 files changed, 95 insertions(+), 29 deletions(-) diff --git a/lib/stdlib/doc/src/gb_sets.xml b/lib/stdlib/doc/src/gb_sets.xml index 9aafca90c3..3477c2c90e 100644 --- a/lib/stdlib/doc/src/gb_sets.xml +++ b/lib/stdlib/doc/src/gb_sets.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2001</year><year>2021</year> + <year>2001</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -29,13 +29,21 @@ <rev></rev> </header> <module since="">gb_sets</module> - <modulesummary>General balanced trees.</modulesummary> + <modulesummary>Sets represented by general balanced trees.</modulesummary> <description> <p>This module provides ordered sets using Prof. Arne Andersson's General Balanced Trees. Ordered sets can be much more efficient than using ordered lists, for larger sets, but depends on the application.</p> + <p>The data representing a set as used by this module is to be + regarded as opaque by other modules. In abstract terms, the + representation is a composite type of existing Erlang terms. See + note on <seeguide + marker="system/reference_manual:data_types#no_user_types">data + types</seeguide>. Any code assuming knowledge of the format is + running on thin ice.</p> + <p>This module considers two elements as different if and only if they do not compare equal (<c>==</c>).</p> </description> @@ -304,8 +312,14 @@ <name name="is_set" arity="1" since=""/> <fsummary>Test for a set.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> appears to be a set, - otherwise <c>false</c>.</p> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> appears to + be a set, otherwise <c>false</c>. This function will return + <c>true</c> for any term that coincides with the + representation of a <c>gb_set</c>, while not really being a + <c>gb_set</c>, thus it might return false positive results. + See also note on <seeguide + marker="system/reference_manual:data_types#no_user_types">data + types</seeguide>.</p> </desc> </func> diff --git a/lib/stdlib/doc/src/ordsets.xml b/lib/stdlib/doc/src/ordsets.xml index e4540e9217..35127dcf95 100644 --- a/lib/stdlib/doc/src/ordsets.xml +++ b/lib/stdlib/doc/src/ordsets.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2021</year> + <year>1996</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -155,7 +155,9 @@ <fsummary>Test for an <c>Ordset</c>.</fsummary> <desc> <p>Returns <c>true</c> if <c><anno>Ordset</anno></c> is an ordered set - of elements, otherwise <c>false</c>.</p> + of elements, otherwise <c>false</c>. This function will + return <c>true</c> for any ordered list, even when not + constructed by the functions in this module.</p> </desc> </func> diff --git a/lib/stdlib/doc/src/queue.xml b/lib/stdlib/doc/src/queue.xml index e2ffffd2f7..2e6f424a84 100644 --- a/lib/stdlib/doc/src/queue.xml +++ b/lib/stdlib/doc/src/queue.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2021</year> + <year>1996</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -48,9 +48,13 @@ <p>Some functions, where noted, fail with reason <c>empty</c> for an empty queue.</p> - <p>The data representing a queue as used by this module - is to be regarded as opaque by other modules. Any code - assuming knowledge of the format is running on thin ice.</p> + <p>The data representing a queue as used by this module is to be + regarded as opaque by other modules. In abstract terms, the + representation is a composite type of existing Erlang terms. See + note on <seeguide + marker="system/reference_manual:data_types#no_user_types">data + types</seeguide>. Any code assuming knowledge of the format is + running on thin ice.</p> <p>All operations have an amortized O(1) running time, except <seemfa marker="#all/2"><c>all/2</c></seemfa>, @@ -285,8 +289,13 @@ <name name="is_queue" arity="1" since=""/> <fsummary>Test if a term is a queue.</fsummary> <desc> - <p>Tests if <c><anno>Term</anno></c> is a queue and returns <c>true</c> - if so, otherwise <c>false</c>.</p> + <p>Tests if <c><anno>Term</anno></c> is a queue and returns + <c>true</c> if so, otherwise <c>false</c>. Note that the test + will return <c>true</c> for a term coinciding with the + representation of a queue, even when not constructed by thus + module. See also note on <seeguide + marker="system/reference_manual:data_types#no_user_types">data + types</seeguide>.</p> </desc> </func> diff --git a/lib/stdlib/doc/src/sets.xml b/lib/stdlib/doc/src/sets.xml index 5d81ca4f0d..53b64a3ac0 100644 --- a/lib/stdlib/doc/src/sets.xml +++ b/lib/stdlib/doc/src/sets.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2000</year><year>2021</year> + <year>2000</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -35,8 +35,17 @@ <module since="">sets</module> <modulesummary>Functions for set manipulation.</modulesummary> <description> - <p>Sets are collections of elements with no duplicate elements. - The representation of a set is undefined.</p> + <p>Sets are collections of elements with no duplicate + elements.</p> + + <p>The data representing a set as used by this module is to be + regarded as opaque by other modules. In abstract terms, the + representation is a composite type of existing Erlang terms. See + note on <seeguide + marker="system/reference_manual:data_types#no_user_types">data + types</seeguide>. Any code assuming knowledge of the format is + running on thin ice.</p> + <p>This module provides the same interface as the <seeerl marker="ordsets"><c>ordsets(3)</c></seeerl> module @@ -174,8 +183,13 @@ <name name="is_set" arity="1" since=""/> <fsummary>Test for a <c>Set</c>.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>Set</anno></c> is a set of - elements, otherwise <c>false</c>.</p> + <p>Returns <c>true</c> if <c><anno>Set</anno></c> appears to + be a set of elements, otherwise <c>false</c>. Note that the + test is shallow and will return <c>true</c> for any term that + coincides with the possible representations of a set. See + also note on <seeguide + marker="system/reference_manual:data_types#no_user_types">data + types</seeguide>.</p> </desc> </func> diff --git a/lib/stdlib/doc/src/sofs.xml b/lib/stdlib/doc/src/sofs.xml index 9b96c4d39a..6d47054cb8 100644 --- a/lib/stdlib/doc/src/sofs.xml +++ b/lib/stdlib/doc/src/sofs.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2001</year><year>2020</year> + <year>2001</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -40,6 +40,14 @@ collection of elements; every element belongs to the set, and the set contains every element.</p> + <p>The data representing <c>sofs</c> as used by this module is to + be regarded as opaque by other modules. In abstract terms, the + representation is a composite type of existing Erlang terms. See + note on <seeguide + marker="system/reference_manual:data_types#no_user_types">data + types</seeguide>. Any code assuming knowledge of the format is + running on thin ice.</p> + <p>Given a set A and a sentence S(x), where x is a free variable, a new set B whose elements are exactly those elements of A for which S(x) holds can be formed, this is denoted B = @@ -1167,20 +1175,31 @@ true</pre> <name name="is_set" arity="1" since=""/> <fsummary>Test for an unordered set.</fsummary> <desc> - <p>Returns <c>true</c> if <c><anno>AnySet</anno></c> is - an <seeerl marker="#sets_definition">unordered set</seeerl>, and - <c>false</c> if <c><anno>AnySet</anno></c> is an ordered set or an - atomic set.</p> + <p>Returns <c>true</c> if <c><anno>AnySet</anno></c> appears + to be an <seeerl marker="#sets_definition">unordered + set</seeerl>, and <c>false</c> if <c><anno>AnySet</anno></c> + is an ordered set or an atomic set or any other term. Note + that the test is shallow and this function will return + <c>true</c> for any term that coincides with the + representation of an unordered set. See also note on + <seeguide + marker="system/reference_manual:data_types#no_user_types">data + types</seeguide>.</p> </desc> </func> <func> <name name="is_sofs_set" arity="1" since=""/> - <fsummary>Test for an unordered set.</fsummary> - <desc> - <p>Returns <c>true</c> if <c><anno>Term</anno></c> is - an <seeerl marker="#sets_definition">unordered set</seeerl>, an - ordered set, or an atomic set, otherwise <c>false</c>.</p> + <fsummary>Test for a sofs set.</fsummary> + <desc> + <p>Returns <c>true</c> if <c><anno>Term</anno></c> appears to + be an <seeerl marker="#sets_definition">unordered + set</seeerl>, an ordered set, or an atomic set, otherwise + <c>false</c>. Note that this function will return <c>true</c> + for any term that coincides with the representation of a + <c>sofs</c> set. See also note on <seeguide + marker="system/reference_manual:data_types#no_user_types">data + types</seeguide>.</p> </desc> </func> diff --git a/system/doc/reference_manual/data_types.xml b/system/doc/reference_manual/data_types.xml index 15983ebbf9..3c12fa4b0e 100644 --- a/system/doc/reference_manual/data_types.xml +++ b/system/doc/reference_manual/data_types.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2021</year> + <year>2003</year><year>2022</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -30,7 +30,15 @@ <file>data_types.xml</file> </header> <p>Erlang provides a number of data types, which are listed in - this section.</p> + this section.</p> + + <marker id="no_user_types" /> + <p>Note that Erlang has no user defined types, only composite + types (data structures) made of Erlang terms. This means that any + function testing for a composite type, typically named + <c>is_type/1</c>, might return <c>true</c> for a term + that coincides with the chosen representation. The corresponding + functions for built in types do not suffer from this.</p> <section> <title>Terms</title> -- 2.34.1
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
