From dc2307c5ae490efa3cb248c2da7fb72ccb90d464 Mon Sep 17 00:00:00 2001
From: "Peter D. Barnes, Jr." <barnes26@llnl.gov>
Date: Thu, 4 Dec 2014 10:02:36 -0800
Subject: [PATCH] Deprecate AddTraceSource without callback signature.

---
 CHANGES.html              |  9 ++++++++-
 src/core/model/type-id.cc | 12 ++++++++++--
 src/core/model/type-id.h  | 20 ++++++++++++++++++--
 3 files changed, 36 insertions(+), 5 deletions(-)

diff --git a/CHANGES.html b/CHANGES.html
index 16969e4e8..f87691b85 100644
--- a/CHANGES.html
+++ b/CHANGES.html
@@ -76,10 +76,17 @@ us a note on ns-developers mailing list.</p>
   <li> The attribute 'Recievers' in class YansWifiPhy was misspelled, so
        this has been corrected to 'Receivers'.
   </li>
+  <li> We have now documented the callback function signatures
+       for all TracedSources, using an extra (fourth) argument to
+       TypeId::AddTraceSource to pass the fully-qualified name
+       of the signature typedef.  To ensure that future TraceSources
+       are similarly documented we have deprecated the three
+       argument version of AddTraceSource.
+  </li>	
 </ul>
 
 <h2>Changes to build system:</h2>
-<ul> 
+<ul>
   <li> waf was upgraded to version 1.7.16
   </li>
 </ul>
diff --git a/src/core/model/type-id.cc b/src/core/model/type-id.cc
index d865cca44..cc1c82f94 100644
--- a/src/core/model/type-id.cc
+++ b/src/core/model/type-id.cc
@@ -641,7 +641,7 @@ TypeId::SetGroupName (std::string groupName)
   Singleton<IidManager>::Get ()->SetGroupName (m_tid, groupName);
   return *this;
 }
-TypeId
+TypeId 
 TypeId::SetSize (std::size_t size)
 {
   NS_LOG_FUNCTION (this << size);
@@ -803,11 +803,19 @@ TypeId::GetTraceSource(uint32_t i) const
   return Singleton<IidManager>::Get ()->GetTraceSource(m_tid, i);
 }
 
+TypeId 
+TypeId::AddTraceSource (std::string name,
+                        std::string help,
+                        Ptr<const TraceSourceAccessor> accessor)
+{
+  return AddTraceSource (name, help, accessor, "(not yet documented)");
+}
+
 TypeId 
 TypeId::AddTraceSource (std::string name,
                         std::string help,
                         Ptr<const TraceSourceAccessor> accessor,
-                        std::string callback /* = "(not yet documented)" */)
+                        std::string callback)
 {
   NS_LOG_FUNCTION (this << name << help << accessor);
   Singleton<IidManager>::Get ()->AddTraceSource (m_tid, name, help, accessor, callback);
diff --git a/src/core/model/type-id.h b/src/core/model/type-id.h
index ea851c55b..ed67ea469 100644
--- a/src/core/model/type-id.h
+++ b/src/core/model/type-id.h
@@ -25,6 +25,7 @@
 #include "trace-source-accessor.h"
 #include "attribute-helper.h"
 #include "callback.h"
+#include "deprecated.h"
 #include "hash.h"
 #include <string>
 #include <stdint.h>
@@ -46,7 +47,7 @@ class ObjectBase;
  *
  * \internal
  *  See the discussion in IidManager about hash chaining of TypeId's.
-  */
+ */
 class TypeId
 {
 public:
@@ -315,6 +316,21 @@ public:
                        Ptr<const AttributeAccessor> accessor,
                        Ptr<const AttributeChecker> checker);
 
+  /**
+   * \param name the name of the new trace source
+   * \param help some help text which describes the purpose of this
+   *        trace source.
+   * \param accessor a pointer to a TraceSourceAccessor which can be
+   *        used to connect/disconnect sinks to this trace source.
+   * \param callback fully qualified typedef name for the callback signature.
+   *        Generally this should begin with the "ns3::" namespace qualifier.
+   * \returns this TypeId instance.
+   */
+  TypeId AddTraceSource (std::string name,
+                         std::string help,
+                         Ptr<const TraceSourceAccessor> accessor)
+    NS_DEPRECATED;
+  
   /**
    * \param name the name of the new trace source
    * \param help some help text which describes the purpose of this
@@ -328,7 +344,7 @@ public:
   TypeId AddTraceSource (std::string name,
                          std::string help,
                          Ptr<const TraceSourceAccessor> accessor,
-                         std::string callback = "(not yet documented)" );
+                         std::string callback);
 
   TypeId HideFromDocumentation (void);