util: give examples for NDN_CXX_DEPRECATED
refs #4566
Change-Id: Iaaebf31d52b9000d0e2ed279b4b8c9a69d0c399b
diff --git a/src/util/backports.hpp b/src/util/backports.hpp
index 1fd375e..18a011ea 100644
--- a/src/util/backports.hpp
+++ b/src/util/backports.hpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
- * Copyright (c) 2015-2017 Regents of the University of California.
+ * Copyright (c) 2013-2018 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -49,6 +49,29 @@
#else
# define NDN_CXX_DEPRECATED_MSG(msg)
#endif
+
+/** \brief Mark a type, variable, or function as deprecated.
+ *
+ * To deprecate a type \c DeprecatedType:
+ * \code
+ * typedef ModernType DeprecatedType NDN_CXX_DEPRECATED;
+ * \endcode
+ * This macro can only be applied to a typedef, not directly on a class.
+ *
+ * To deprecate a variable or class member \c deprecatedVar:
+ * \code
+ * int deprecatedVar NDN_CXX_DEPRECATED;
+ * \endcode
+ *
+ * To deprecate a function \c deprecatedFunc:
+ * \code
+ * NDN_CXX_DEPRECATED
+ * void
+ * deprecatedFunc(int a, NamedEnum b)
+ * {
+ * }
+ * \endcode
+ */
#define NDN_CXX_DEPRECATED NDN_CXX_DEPRECATED_MSG("")
#if (__cplusplus > 201402L) && NDN_CXX_HAS_CPP_ATTRIBUTE(fallthrough)
diff --git a/tests/unit-tests/util/backports.t.cpp b/tests/unit-tests/util/backports.t.cpp
index 21afb0d..3722834 100644
--- a/tests/unit-tests/util/backports.t.cpp
+++ b/tests/unit-tests/util/backports.t.cpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
-/**
- * Copyright (c) 2013-2017 Regents of the University of California.
+/*
+ * Copyright (c) 2013-2018 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -30,6 +30,41 @@
BOOST_AUTO_TEST_SUITE(Util)
BOOST_AUTO_TEST_SUITE(TestBackports)
+namespace deprecated_test {
+
+// Deprecate a variable.
+static int g_deprecatedVar NDN_CXX_DEPRECATED = 0;
+
+// Deprecate an enum member (a variable).
+enum NamedEnum
+{
+ ModernEnumMember,
+};
+constexpr NamedEnum DeprecatedEnumMember NDN_CXX_DEPRECATED = ModernEnumMember;
+
+// Deprecate a type.
+class ModernType
+{
+public:
+ // Deprecate a function.
+ NDN_CXX_DEPRECATED
+ void
+ deprecatedFunc(int a, NamedEnum b)
+ {
+ }
+};
+typedef ModernType DeprecatedType NDN_CXX_DEPRECATED;
+
+} // namespace deprecated_test
+
+BOOST_AUTO_TEST_CASE(Deprecated)
+{
+ using namespace deprecated_test;
+ DeprecatedType instance;
+ instance.deprecatedFunc(g_deprecatedVar, DeprecatedEnumMember);
+ BOOST_CHECK(true);
+}
+
BOOST_AUTO_TEST_CASE(MakeUnique)
{
std::unique_ptr<int> v0 = make_unique<int>();