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 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Authors: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 */
8
9#ifndef NS3_DEPRECATED_H
10#define NS3_DEPRECATED_H
11
12/**
13 * @file
14 * @ingroup deprecation
15 * NS_DEPRECATED macro definition.
16 */
17
18/**
19 * @defgroup deprecation Deprecation
20 * @ingroup core
21 */
22
23/**
24 * @ingroup deprecation
25 * @def NS_DEPRECATED
26 * Mark a function as deprecated.
27 *
28 * Users should expect deprecated features to be removed eventually.
29 *
30 * When deprecating a feature, please update the documentation
31 * with information for users on how to update their code.
32 *
33 * The following snippet shows an example of how to deprecate the function SomethingUseful()
34 * in favor of the new function TheNewWay().
35 * Note: in the following snippet, the Doxygen blocks are not following the ns-3 style.
36 * This allows the code to be safely embedded in the documentation.
37 *
38 * @code
39 * /// Do something useful.
40 * ///
41 * /// \deprecated This method will go away in future versions of ns-3.
42 * /// See instead TheNewWay().
43 * NS_DEPRECATED_3_XX("see TheNewWay")
44 * void SomethingUseful();
45 *
46 * /// Do something more useful.
47 * void TheNewWay();
48 * @endcode
49 *
50 * Please follow these two guidelines to ease future maintenance
51 * (primarily the eventual removal of the deprecated code):
52 *
53 * 1. Please use the versioned form `NS_DEPRECATED_3_XX`,
54 * not the generic `NS_DEPRECATED`.
55 *
56 * 2. Typically only the declaration needs to be deprecated,
57 *
58 * @code
59 * NS_DEPRECATED_3_XX("see TheNewWay")
60 * void SomethingUseful();
61 * @endcode
62 *
63 * but it's helpful to put the same macro as a comment
64 * at the site of the definition, to make it easier to find
65 * all the bits which eventually have to be removed:
66 *
67 * @code
68 * // NS_DEPRECATED_3_XX("see TheNewWay")
69 * void SomethingUseful() { ... }
70 * @endcode
71 *
72 * @note Sometimes it is necessary to silence a deprecation warning.
73 * Even though this is highly discouraged, if necessary it is possible to use:
74 * @code
75 * NS_WARNING_PUSH_DEPRECATED;
76 * // call to a function or class that has been deprecated.
77 * NS_WARNING_POP;
78 * @endcode
79 * These macros are defined in warnings.h
80 *
81 * @param msg Optional message to add to the compiler warning.
82 *
83 */
84#define NS_DEPRECATED(msg) /** \deprecated msg */ [[deprecated(msg)]]
85
86/**
87 * @ingroup deprecation
88 * @def NS_DEPRECATED_3_44
89 * Tag for things deprecated in version ns-3.44.
90 */
91#define NS_DEPRECATED_3_44(msg) NS_DEPRECATED("Deprecated in ns-3.44: " msg)
92
93/**
94 * @ingroup deprecation
95 * @def NS_DEPRECATED_3_43
96 * Tag for things deprecated in version ns-3.43.
97 */
98#define NS_DEPRECATED_3_43(msg) NS_DEPRECATED("Deprecated in ns-3.43: " msg)
99
100/**
101 * @ingroup deprecation
102 * @def NS_DEPRECATED_3_42
103 * Tag for things deprecated in version ns-3.42.
104 */
105#define NS_DEPRECATED_3_42(msg) NS_DEPRECATED("Deprecated in ns-3.42: " msg)
106
107/**
108 * @ingroup deprecation
109 * @def NS_DEPRECATED_3_41
110 * Tag for things deprecated in version ns-3.41.
111 */
112#define NS_DEPRECATED_3_41(msg) NS_DEPRECATED("Deprecated in ns-3.41: " msg)
113
114/**
115 * @ingroup deprecation
116 * @def NS_DEPRECATED_3_40
117 * Tag for things deprecated in version ns-3.40.
118 */
119#define NS_DEPRECATED_3_40(msg) NS_DEPRECATED("Deprecated in ns-3.40: " msg)
120
121#endif /* NS3_DEPRECATED_H */