[Doxygen] Better documentation for NS_DEPRECATED

doc/doxygen.conf

@@ -857,6 +857,7 @@ EXAMPLE_PATH           = src/aodv/examples \
                          src/click/examples \
                          src/config-store/examples \
                          src/core/examples \
+			 src/core/doc \
                          src/csma/examples \
                          src/csma-layout/examples \
                          src/dsdv/examples \

src/core/doc/deprecated-example.h

@@ -0,0 +1,38 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) 2015 Lawrence Livermore National Laboratory
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation;
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ *
+ * Authors: Peter D. Barnes, Jr. <pdbarnes@llnl.gov>
+ */
+
+/* 
+ * This is an example included in the doxygen-generated documentation
+ * for NS_DEPRECATED.
+ */
+
+// [doxygen snippet]
+/*
+ * Do something useful.
+ *
+ * \deprecated This method will go away in future versions of ns-3.
+ * See instead TheNewWay()
+ */
+void SomethingUseful (void); 
+/*
+ * Do something more useful.
+ */
+void TheNewWay (void);
+// [doxygen snippet]

src/core/model/deprecated.h

@@ -36,7 +36,11 @@
  *
  * When deprecating a feature, please update the documentation
  * with information for users on how to update their code.
+ *
+ * For example,
+ * \snippet src/core/doc/deprecated-example.h doxygen snippet
  */
+
 #if defined(__GNUC__) && (__GNUC__ == 4) && (__GNUC_MINOR__ > 1)
 #define NS_DEPRECATED __attribute__ ((deprecated))
 #else

src/core/model/type-id.h

@@ -331,6 +331,9 @@ public:
    * \param callback fully qualified typedef name for the callback signature.
    *        Generally this should begin with the "ns3::" namespace qualifier.
    * \returns this TypeId instance.
+   *
+   * \deprecated This method will go away in future versions of ns-3.
+   * See instead AddTraceSource(std::string,std::string,Ptr<const TraceSourceAccessor>,std::string)
    */
   TypeId AddTraceSource (std::string name,
                          std::string help,

src/network/utils/data-rate.h

@@ -184,6 +184,9 @@ public:
    * Calculates the transmission time at this data rate
    * \param bytes The number of bytes (not bits) for which to calculate
    * \return The transmission time in seconds for the number of bytes specified
+   *
+   * \deprecated This method will go away in future versions of ns-3.
+   * See instead CalculateBytesTxTime()
    */
   double CalculateTxTime (uint32_t bytes) const NS_DEPRECATED;