From 48d8bf45f83fa3f30be326647778669e74a29cb7 Mon Sep 17 00:00:00 2001
From: Tom Henderson <tomh@tomh.org>
Date: Sun, 28 Nov 2021 17:40:32 +0100
Subject: [PATCH] Add wifi model subheader on changes across releases

---
 doc/models/Makefile                    |  1 +
 src/wifi/doc/source/wifi-changelog.rst | 35 ++++++++++++++++++++++++++
 src/wifi/doc/source/wifi-user.rst      |  2 ++
 src/wifi/doc/source/wifi.rst           |  1 +
 4 files changed, 39 insertions(+)
 create mode 100644 src/wifi/doc/source/wifi-changelog.rst

diff --git a/doc/models/Makefile b/doc/models/Makefile
index 05371ceaf..8d90f5ad5 100644
--- a/doc/models/Makefile
+++ b/doc/models/Makefile
@@ -76,6 +76,7 @@ SOURCES = \
 	$(SRC)/wifi/doc/source/wifi-design.rst \
 	$(SRC)/wifi/doc/source/wifi-user.rst \
 	$(SRC)/wifi/doc/source/wifi-testing.rst \
+	$(SRC)/wifi/doc/source/wifi-changelog.rst \
 	$(SRC)/wifi/doc/source/wifi-references.rst \
 	$(SRC)/wimax/doc/wimax.rst \
 	$(SRC)/uan/doc/uan.rst \
diff --git a/src/wifi/doc/source/wifi-changelog.rst b/src/wifi/doc/source/wifi-changelog.rst
new file mode 100644
index 000000000..721a59e4e
--- /dev/null
+++ b/src/wifi/doc/source/wifi-changelog.rst
@@ -0,0 +1,35 @@
+.. include:: replace.txt
+.. highlight:: cpp
+
+.. _sec-wifi-changelog-doc:
+
+++++++++++++++++++++++++++++++++++++++++
+API and behavior changes across releases
+++++++++++++++++++++++++++++++++++++++++
+
+This page tracks the most relevant changes to the API and behavior of the wifi
+module occurred across the various releases of |ns3|.
+
+ChannelSettings attribute
++++++++++++++++++++++++++
+
+Prior to ns-3.36, channels, channel widths, and operating bands were set
+separately.  As of ns-3.36, a new tuple object that we call ChannelSettings has
+consolidated all of these settings.  Users should specify the channel number,
+channel width, frequency band, and primary channel index as a tuple (and
+continue to set the Wi-Fi standard separately).
+
+For instance, where pre-ns-3.36 code may have said::
+
+    WifiPhyHelper phy;
+    phy.Set("ChannelNumber", UintegerValue (36));
+
+the equivalent new code is::
+
+    WifiPhyHelper phy;
+    phy.Set ("ChannelSettings", StringValue ("{36, 20, BAND_5GHZ, 0}"));
+
+which denotes that channel 36 is used on a 20 MHz channel in the 5GHz band,
+and because a larger channel width greater than 20 MHz is not being used, there
+is no need to indicate the primary 20 MHz channel so it is set to zero in the
+last argument. Users can read :ref:`Channel-settings` for more details.
diff --git a/src/wifi/doc/source/wifi-user.rst b/src/wifi/doc/source/wifi-user.rst
index 8ce168367..d56ae6755 100644
--- a/src/wifi/doc/source/wifi-user.rst
+++ b/src/wifi/doc/source/wifi-user.rst
@@ -194,6 +194,8 @@ For example, this code configures a node with 3 antennas that supports 2 spatial
   NetDeviceContainer apDevice;
   apDevice = wifi.Install (phy, mac, wifiApNode);
 
+.. _Channel-settings:
+
 Channel, frequency, channel width, and band configuration
 =========================================================
 
diff --git a/src/wifi/doc/source/wifi.rst b/src/wifi/doc/source/wifi.rst
index 7a83215f9..675472c55 100644
--- a/src/wifi/doc/source/wifi.rst
+++ b/src/wifi/doc/source/wifi.rst
@@ -7,4 +7,5 @@
     wifi-design
     wifi-user
     wifi-testing
+    wifi-changelog
     wifi-references