From 1bc7047af724f9d6282f7cc79289ecdffe084d1c Mon Sep 17 00:00:00 2001
From: duck <me@duck.me.uk>
Date: Sat, 27 Jun 2020 16:21:17 +0000
Subject: [PATCH] Doc: Acknowledge integer type mismatch in certain admin
 packets using AdminUpdateType (#8238)

---
 docs/admin_network.md        | 14 ++++++++++++++
 src/network/core/tcp_admin.h |  4 ++--
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/docs/admin_network.md b/docs/admin_network.md
index ff5ea7c27a..4703df322a 100644
--- a/docs/admin_network.md
+++ b/docs/admin_network.md
@@ -86,6 +86,9 @@ Last updated:    2011-01-20
   Note: not every update type supports every frequency. If in doubt, you can
   verify against the data received in `ADMIN_PACKET_SERVER_PROTOCOL`.
 
+  Please note the potential gotcha in the "Certain packet information" section below
+  when using the `ADMIN_UPDATE_FREQUENCY` packet.
+
   The server will not confirm your registered update. However, asking for an
   invalid `AdminUpdateType` or a not supported `AdminUpdateFrequency` you will be
   disconnected from the server with `NETWORK_ERROR_ILLEGAL_PACKET`.
@@ -143,6 +146,9 @@ Last updated:    2011-01-20
     - ADMIN_UPDATE_COMPANY_STATS
     - ADMIN_UPDATE_CMD_NAMES
 
+  Please note the potential gotcha in the "Certain packet information" section below
+  when using the `ADMIN_POLL` packet.
+
   `ADMIN_UPDATE_CLIENT_INFO` and `ADMIN_UPDATE_COMPANY_INFO` accept an additional
   parameter. This parameter is used to specify a certain client or company.
   Setting this parameter to `UINT32_MAX (0xFFFFFFFF)` will tell the server you
@@ -213,6 +219,14 @@ Last updated:    2011-01-20
 
 ## 7.0) Certain packet information
 
+  `ADMIN_PACKET_ADMIN_UPDATE_FREQUENCY` and `ADMIN_PACKET_ADMIN_POLL`
+
+    Potential gotcha: the AdminUpdateType integer type used is a
+    uint16 for `UPDATE_FREQUENCY`, and a uint8 for `POLL`.
+    This is due to boring legacy reasons.
+    It is safe to cast between the two when sending
+    (i.e cast from a uint8 to a uint16).
+
   All `ADMIN_PACKET_SERVER_*` packets have an enum value greater 100.
 
   `ADMIN_PACKET_SERVER_WELCOME`
diff --git a/src/network/core/tcp_admin.h b/src/network/core/tcp_admin.h
index 979e5963f0..dc9753e89f 100644
--- a/src/network/core/tcp_admin.h
+++ b/src/network/core/tcp_admin.h
@@ -134,7 +134,7 @@ protected:
 
 	/**
 	 * Register updates to be sent at certain frequencies (as announced in the PROTOCOL packet):
-	 * uint16  Update type (see #AdminUpdateType).
+	 * uint16  Update type (see #AdminUpdateType). Note integer type - see "Certain Packet Information" in docs/admin_network.md.
 	 * uint16  Update frequency (see #AdminUpdateFrequency), setting #ADMIN_FREQUENCY_POLL is always ignored.
 	 * @param p The packet that was just received.
 	 * @return The state the network should have.
@@ -143,7 +143,7 @@ protected:
 
 	/**
 	 * Poll the server for certain updates, an invalid poll (e.g. not existent id) gets silently dropped:
-	 * uint8   #AdminUpdateType the server should answer for, only if #AdminUpdateFrequency #ADMIN_FREQUENCY_POLL is advertised in the PROTOCOL packet.
+	 * uint8   #AdminUpdateType the server should answer for, only if #AdminUpdateFrequency #ADMIN_FREQUENCY_POLL is advertised in the PROTOCOL packet. Note integer type - see "Certain Packet Information" in docs/admin_network.md.
 	 * uint32  ID relevant to the packet type, e.g.
 	 *          - the client ID for #ADMIN_UPDATE_CLIENT_INFO. Use UINT32_MAX to show all clients.
 	 *          - the company ID for #ADMIN_UPDATE_COMPANY_INFO. Use UINT32_MAX to show all companies.