From 9b7088d3636b52070e2f53c2dacf3069b61b0370 Mon Sep 17 00:00:00 2001
From: Gabriel Ferreira <gabrielcarvfer@gmail.com>
Date: Sat, 28 Oct 2023 15:03:23 -0300
Subject: [PATCH] doc: add note regarding template classes and duplicate TypeId
 allocation

---
 doc/manual/source/new-models.rst | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/doc/manual/source/new-models.rst b/doc/manual/source/new-models.rst
index db813d2c1..5f88b6c23 100644
--- a/doc/manual/source/new-models.rst
+++ b/doc/manual/source/new-models.rst
@@ -385,6 +385,29 @@ every class that defines a new GetTypeId method, and it does the actual
 registration of the class into the system.  The :ref:`Object-model` chapter
 discusses this in more detail.
 
+Note: Template classes should both export the instantiated template and call
+``NS_OBJECT_TEMPLATE_CLASS_DEFINE (TemplateClass, TemplateArgument);``
+to prevent the same template from being instantiated more than a single
+time in different modules. This prevents errors such as
+``Trying to allocate twice the same uid: TemplateClass<TemplateArgument>``.
+
+An example for the ``CounterCalculator<uint32_t>``::
+
+    //.h file
+    namespace ns3
+    {
+        extern template class CounterCalculator<uint32_t>;
+    }
+    //.cc file
+    #include <ns3/.h file>
+    namespace ns3
+    {
+        NS_OBJECT_TEMPLATE_CLASS_DEFINE (CounterCalculator, uint32_t);
+    }
+
+More details can be found in `issue #761 <https://gitlab.com/nsnam/ns-3-dev/-/issues/761>`_.
+
+
 Including External Files
 ++++++++++++++++++++++++