A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
deprecated.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2008 INRIA
3 *
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License version 2 as
6 * published by the Free Software Foundation;
7 *
8 * This program is distributed in the hope that it will be useful,
9 * but WITHOUT ANY WARRANTY; without even the implied warranty of
10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 * GNU General Public License for more details.
12 *
13 * You should have received a copy of the GNU General Public License
14 * along with this program; if not, write to the Free Software
15 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
16 *
17 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
18 */
19
20#ifndef NS3_DEPRECATED_H
21#define NS3_DEPRECATED_H
22
23/**
24 * \file
25 * \ingroup deprecation
26 * NS_DEPRECATED macro definition.
27 */
28
29/**
30 * \defgroup deprecation Deprecation
31 * \ingroup core
32 */
33
34/**
35 * \ingroup deprecation
36 * \def NS_DEPRECATED
37 * Mark a function as deprecated.
38 *
39 * Users should expect deprecated features to be removed eventually.
40 *
41 * When deprecating a feature, please update the documentation
42 * with information for users on how to update their code.
43 *
44 * The following snippet shows an example of how to deprecate the function SomethingUseful()
45 * in favor of the new function TheNewWay().
46 * Note: in the following snippet, the Doxygen blocks are not following the ns-3 style.
47 * This allows the code to be safely embedded in the documentation.
48 *
49 * \code
50 * /// Do something useful.
51 * ///
52 * /// \deprecated This method will go away in future versions of ns-3.
53 * /// See instead TheNewWay().
54 * NS_DEPRECATED_3_XX("see TheNewWay")
55 * void SomethingUseful();
56 *
57 * /// Do something more useful.
58 * void TheNewWay();
59 * \endcode
60 *
61 * Please follow these two guidelines to ease future maintenance
62 * (primarily the eventual removal of the deprecated code):
63 *
64 * 1. Please use the versioned form `NS_DEPRECATED_3_XX`,
65 * not the generic `NS_DEPRECATED`.
66 *
67 * 2. Typically only the declaration needs to be deprecated,
68 *
69 * \code
70 * NS_DEPRECATED_3_XX("see TheNewWay")
71 * void SomethingUseful();
72 * \endcode
73 *
74 * but it's helpful to put the same macro as a comment
75 * at the site of the definition, to make it easier to find
76 * all the bits which eventually have to be removed:
77 *
78 * \code
79 * // NS_DEPRECATED_3_XX("see TheNewWay")
80 * void SomethingUseful() { ... }
81 * \endcode
82 *
83 * \note Sometimes it is necessary to silence a deprecation warning.
84 * Even though this is highly discouraged, if necessary it is possible to use:
85 * \code
86 * NS_WARNING_PUSH_DEPRECATED;
87 * // call to a function or class that has been deprecated.
88 * NS_WARNING_POP;
89 * \endcode
90 * These macros are defined in warnings.h
91 *
92 * \param msg Optional message to add to the compiler warning.
93 *
94 */
95#define NS_DEPRECATED(msg) [[deprecated(msg)]]
96
97/**
98 * \ingroup deprecation
99 * \def NS_DEPRECATED_3_42
100 * Tag for things deprecated in version ns-3.42.
101 */
102#define NS_DEPRECATED_3_42(msg) NS_DEPRECATED("Deprecated in ns-3.42: " msg)
103
104/**
105 * \ingroup deprecation
106 * \def NS_DEPRECATED_3_41
107 * Tag for things deprecated in version ns-3.41.
108 */
109#define NS_DEPRECATED_3_41(msg) NS_DEPRECATED("Deprecated in ns-3.41: " msg)
110
111/**
112 * \ingroup deprecation
113 * \def NS_DEPRECATED_3_40
114 * Tag for things deprecated in version ns-3.40.
115 */
116#define NS_DEPRECATED_3_40(msg) NS_DEPRECATED("Deprecated in ns-3.40: " msg)
117
118#endif /* NS3_DEPRECATED_H */