From b506ec1bc231bac27a7594623ec522cc845db837 Mon Sep 17 00:00:00 2001
From: Tom Henderson <tomh@tomh.org>
Date: Tue, 7 Jan 2025 10:38:53 -0800
Subject: [PATCH] doc: Clarify specialization of GetInstanceTypeId()

---
 CHANGES.md                       |  2 +-
 doc/manual/source/attributes.rst | 11 +++++++----
 src/core/model/object-base.h     |  7 ++++---
 3 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/CHANGES.md b/CHANGES.md
index 4be1f8705..ef21c6a3d 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -20,6 +20,7 @@ This file is a best-effort approach to solving this issue; we will do our best b
 
 ### Changes to existing API
 
+* (core) ``Object::GetInstanceTypeId()`` can no longer be specialized by subclasses and any such subclass API should be deleted (the base class will handle it).
 * (internet-apps) Added a parameter to the RADVD helper to announce a prefix without the autoconfiguration flag.
 
 ### Changes to build system
@@ -42,7 +43,6 @@ This file is a best-effort approach to solving this issue; we will do our best b
 * (applications) Deprecated attributes `RemoteAddress` and `RemotePort` in UdpClient, UdpTraceClient and UdpEchoClient. They have been combined into a single `Remote` attribute.
 * (applications) Deprecated attributes `ThreeGppHttpClient::RemoteServerAddress` and `ThreeGppHttpClient::RemoteServerPort`. They have been combined into a single `ThreeGppHttpClient::Remote` attribute.
 * (core) Deprecated `SUPPORTED`, `DEPRECATED` and `OBSOLETE` in `TypeId` class. They have been replaced by `SupportLevel::{SUPPORTED,DEPRECATED,OBSOLETE}`, respectively.
-* (core) ``Object::GetInstanceTypeId()`` can no longer be specialized by subclasses.
 * (lr-wpan) ``LrWpanMac`` is now also aggregated to ``LrWpanNetDevice``.
 * (stats) Deprecated ns3::NaN and ns3::isNaN to use std::nan and std::isnan in their place
 * (tap-bridge) Deprecated "Gateway" attribute.
diff --git a/doc/manual/source/attributes.rst b/doc/manual/source/attributes.rst
index 4e68f3408..d05876484 100644
--- a/doc/manual/source/attributes.rst
+++ b/doc/manual/source/attributes.rst
@@ -801,10 +801,13 @@ follows::
       // continue on with constructor.
     }
 
-Beware that the object and all its derived classes must also implement
-a :cpp:func:`GetInstanceTypeId()` method. Otherwise
-the :cpp:func:`ObjectBase::ConstructSelf()` will not be able to read
-the attributes.
+Classes that derive from :cpp:class:`Object` can not implement (i.e., specialize)
+a :cpp:func:`GetInstanceTypeId()` method; this method is marked `final`
+in :cpp:class:`Object`.  However, classes that instead derive from
+:cpp:class:`ObjectBase` directly (in ns-3, this is usually packet headers and tags),
+must implement :cpp:func:`GetInstanceTypeId()`.  It is recommended that this
+method simply return the value provided by :cpp:func:`GetTypeId()`; see the class
+:cpp:class:`EthernetHeader` in `src/network/utils` directory as an example.
 
 Adding Attributes
 +++++++++++++++++
diff --git a/src/core/model/object-base.h b/src/core/model/object-base.h
index 117781ed3..7c637516e 100644
--- a/src/core/model/object-base.h
+++ b/src/core/model/object-base.h
@@ -175,9 +175,10 @@ class ObjectBase
     /**
      * Get the most derived TypeId for this Object.
      *
-     * This method is typically implemented by ns3::Object::GetInstanceTypeId
-     * but some classes which derive from ns3::ObjectBase directly
-     * have to implement it themselves.
+     * This method is provided by ns3::Object::GetInstanceTypeId
+     * but classes which derive from ns3::ObjectBase directly
+     * have to implement it themselves.  Typically, this method should
+     * simply return the output of `GetTypeId()`.
      *
      * @return The TypeId associated to the most-derived type
      *          of this instance.