[features] Add documentation for features support

5 files changed, 242 insertions, 6 deletions

diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml
index b3259ec630..3a01066410 100644
--- a/system/doc/reference_manual/expressions.xml
+++ b/system/doc/reference_manual/expressions.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>
@@ -397,9 +397,13 @@ is_valid_signal(Signal) ->
   <section>
     <marker id="maybe"></marker>
     <title>Maybe</title>
-    <note><p><c>maybe</c> is an experimental new feature introduced in
-    OTP 25. By default, it is disabled. To enable <c>maybe</c>, use
-    compiler option <c>{enable_feature,maybe_expr}</c>.</p></note>
+    <note><p><c>maybe</c> is an experimental new <seeguide
+    marker="system/reference_manual:features#features">feature</seeguide>
+    introduced in OTP 25. By default, it is disabled. To enable
+    <c>maybe</c>, use compiler option
+    <c>{feature,maybe_expr,enable}</c>.  The feature must also be
+    enabled in the runtime using the <c>-enable-feature</c> option to
+    <c>erl</c>.</p></note>
 
     <code type="erl"><![CDATA[
 maybe
diff --git a/system/doc/reference_manual/features.xml b/system/doc/reference_manual/features.xml
new file mode 100644
index 0000000000..ed254db55a
--- /dev/null
+++ b/system/doc/reference_manual/features.xml
@@ -0,0 +1,218 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2022</year><year>2022</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>Features</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+    <file>features.xml</file>
+  </header>
+  <p>
+    <marker id="features"/>
+    Introduced in OTP 25, Erlang has the concept of selectable features.
+    A feature can change, add or remove behaviour of the language and/or
+    runtime system.  Examples can include
+  </p>
+  <list>
+    <item>Adding new syntactical constructs to the language</item>
+    <item>Change the semantics of an existing construct</item>
+    <item>Change the behaviour of some runtime aspect</item>
+  </list>
+  <p>
+    A feature will start out with a status of experimental part of OTP,
+    making it possible to try out for users and give feedback.  The
+    possibility to try out features is enabled by options to the
+    compiler, directives in a module and options to the runtime system.
+    Even when a feature is not experimental it will still be possible to
+    enable or disable it.  This makes it possible to adapt a code base
+    at a suitable pace instead of being forced when changing to a new
+    release.
+  </p>
+  <p>
+    The status of a feature will eventually end up as being either a
+    permanent part of OTP or rejected, being removed and no longer
+    selectable.
+  </p>
+
+  <section>
+    <title>Life cycle of features</title>
+    <p>A feature is in one of four possible states:</p>
+    <taglist>
+      <tag>Experimental</tag>
+      <item>The initial state, is meant for trying out and collecting
+      feedback.  The feature can be enabled but is disabled by
+      default.</item>
+      <tag>Approved</tag>
+      <item>The feature has been finalised and is now part of OTP.  By
+      default it is enabled, but can be disabled.</item>
+      <tag>Permanent</tag>
+      <item>The feature is now a permanent part of OTP.  It can no
+      longer be disabled.</item>
+      <tag>Rejected</tag>
+      <item>The feature never reached the approved state and will not
+      be part of OTP.  It cannot be enabled.</item>
+    </taglist>
+    <p>
+      After leaving the experimental state, a feature can enter any of
+      the other three states, and if the next state is approved, the
+      feature will eventually end up in the permanent state.  A feature
+      can change state only in connection with a release.
+    </p>
+    <p>
+      A feature may be in the approved state for several releases.
+    </p>
+    <table>
+      <row>
+        <cell>State</cell>
+        <cell>Default</cell>
+        <cell>Configurable</cell>
+        <cell>Available</cell>
+      </row>
+      <row>
+        <cell>Experimental</cell>
+        <cell>disabled</cell>
+        <cell>yes</cell>
+        <cell>yes</cell>
+      </row>
+      <row>
+        <cell>Approved</cell>
+        <cell>enabled</cell>
+        <cell>yes</cell>
+        <cell>yes</cell>
+      </row>
+      <row>
+        <cell>Permanent</cell>
+        <cell>enabled</cell>
+        <cell>no</cell>
+        <cell>yes</cell>
+      </row>
+      <row>
+        <cell>Rejected</cell>
+        <cell>disabled</cell>
+        <cell>no</cell>
+        <cell>no</cell>
+      </row>
+      <tcaption>Feature States</tcaption>
+    </table>
+    <list>
+      <item>Being configurable means the possibility to enable or
+      disable the feature by means of compiler options and directives
+      in the file being compiled.</item>
+      <item>Being available can be seen using the
+      <c>FEATURE_AVAILABLE</c> macro.</item>
+    </list>
+  </section>
+
+  <section>
+    <title>Enabling and Disabling Features</title>
+    <p>To use a feature that is in the experimental state, it has to
+    be enabled during compilation.  This can be done in a number of
+    different ways:
+    </p>
+    <taglist>
+      <tag>Options to <c>erlc</c></tag>
+      <item>Options <seecom
+      marker="erts:erlc#enable-feature"><c>-enable-feature</c></seecom>
+      and <seecom
+      marker="erts:erlc#disable-feature"><c>-disable-feature</c></seecom>
+      can be used to enable or disable individal features.</item>
+      <tag>Compiler options</tag>
+      <item>The compiler option <seeerl
+      marker="compiler:compile#feature-option"><c>{feature,
+      &lt;feature&gt;, enable|disable}</c></seeerl> can be used either
+      as a <c>+&lt;term&gt;</c> option to <c>erlc</c>, in the options
+      argument to function in the <c>compile</c> module, or in the
+      <c>-compile(..)</c> attribute in a file.</item>
+      <tag>The feature directive</tag>
+      <item>Inside a prefix of a module, one can use a <seeerl
+      marker="compiler:compile#feature-directive"><c>-feature(&lt;feature&gt;,
+      enable|disable)</c></seeerl> directive.  This is the preferred
+      method of enabling and disabling features.</item>
+    </taglist>
+    <p>
+      Note that to load a module compiled with features enabled, the
+      corresponding features must be enabled in the runtime.  This
+      is done using options <seecom
+      marker="erts:erl#enable-feature"><c>-enable-feature</c></seecom>
+      and <seecom
+      marker="erts:erl#disable-feature"><c>-disable-feature</c></seecom>
+      to <c>erl</c>.  This is to allow the possibility to prevent
+      the use of experimental features in, e.g., production.  This
+      will catch experimental features used in both own and third
+      party components.  An active choice to use experimental
+      features must be done.
+    </p>
+  </section>
+
+  <section>
+    <title>Preprocessor Additions</title>
+    <p>
+      To allow for conditional compilation during transitioning of a
+      code base and/or trying out experimental features <seeguide
+      marker="system/reference_manual:macros#predefined-macros">feature</seeguide>
+      <c>predefined macros</c> <c>?FEATURE_AVAILABLE(Feature)</c> and
+      <c>?FEATURE_ENABLED(Feature)</c> are available.
+    </p>
+  </section>
+
+  <section>
+    <title>Information about Existing Features</title>
+    <p>
+    The module <c>erl_features</c> <seeerl
+    marker="stdlib:erl_features"><c>erl_features</c></seeerl> exports
+    a number of functions that can be used to obtain information about
+    current features as well as the features used when compiling a
+    module.
+    </p>
+    <p>One can also use the <c>erlc</c> options <seecom
+    marker="erts:erlc#list-features"><c>-list-features</c></seecom>
+    and <seecom
+    marker="erts:erlc#describe-feature"><c>-describe-feature
+    &lt;feature&gt;</c></seecom> to get information about existing
+    features.
+    </p>
+    <p>
+      Additionally, there is the compiler option
+      <seeerl
+      marker="compiler:compile#warn-keywords"><c>warn_keywords</c></seeerl>
+      that can be used to find atoms in the code base that might
+      collide with keywords in features not yet enabled.
+    </p>
+  </section>
+
+  <section>
+    <title>Existing Features</title>
+    <p>
+      The following configurable features exist:
+    </p>
+    <taglist>
+      <tag><c>maybe_expr</c> (experimental)</tag>
+      <item>
+        Implementation of the <seeguide
+        marker="expressions#maybe"><c>maybe</c></seeguide> expression
+        proposed in <url href="https://www.erlang.org/eeps/eep-0049">EEP 49</url>.</item>
+    </taglist>
+  </section>
+</chapter>
diff --git a/system/doc/reference_manual/macros.xml b/system/doc/reference_manual/macros.xml
index 0943dbd56d..ffa5373613 100644
--- a/system/doc/reference_manual/macros.xml
+++ b/system/doc/reference_manual/macros.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>
@@ -134,7 +134,8 @@ bar(X) ->
 
   <section>
     <title>Predefined Macros</title>
-    <p>The following macros are predefined:</p>
+    <p>
+       The following macros are predefined:</p>
     <taglist>
       <tag><c>?MODULE</c></tag>
       <item>The name of the current module.</item>
@@ -155,6 +156,17 @@ bar(X) ->
         application is part of, as an integer. For details, see
         <seemfa marker="erts:erlang#system_info/1"><c>erlang:system_info(otp_release)</c></seemfa>.
         This macro was introduced in OTP release 21.</item>
+        <tag><c>?FEATURE_AVAILABLE(Feature)</c></tag>
+        <item>Expands to <c>true</c> if the <seeguide
+        marker="system/reference_manual:features#features">feature</seeguide>
+        <c>Feature</c> is available.  The feature might or might not
+        be enabled.  This macro was introduced with OTP release
+        25.</item>
+        <tag><c>?FEATURE_ENABLED(Feature)</c></tag>
+        <item>Expands to <c>true</c> if the <seeguide
+        marker="system/reference_manual:features#features">feature</seeguide>
+        <c>Feature</c> is enabled.  This macro was introduced with OTP
+        release 25.</item>
     </taglist>
   </section>
 
diff --git a/system/doc/reference_manual/part.xml b/system/doc/reference_manual/part.xml
index 6076a87bc3..ec2e3e0306 100644
--- a/system/doc/reference_manual/part.xml
+++ b/system/doc/reference_manual/part.xml
@@ -40,6 +40,7 @@
   <xi:include href="macros.xml"/>
   <xi:include href="records.xml"/>
   <xi:include href="errors.xml"/>
+  <xi:include href="features.xml"/>
   <xi:include href="processes.xml"/>
   <xi:include href="distributed.xml"/>
   <xi:include href="code_loading.xml"/>
diff --git a/system/doc/reference_manual/xmlfiles.mk b/system/doc/reference_manual/xmlfiles.mk
index af1c763923..8e2af09699 100644
--- a/system/doc/reference_manual/xmlfiles.mk
+++ b/system/doc/reference_manual/xmlfiles.mk
@@ -27,6 +27,7 @@ REF_MAN_CHAPTER_FILES = \
 	macros.xml \
 	records.xml \
 	errors.xml \
+	features.xml \
 	processes.xml \
 	distributed.xml \
 	code_loading.xml \