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_43
89 * Tag for things deprecated in version ns-3.43.
90 */
91#define NS_DEPRECATED_3_43(msg) NS_DEPRECATED("Deprecated in ns-3.43: " msg)
92
93/**
94 * \ingroup deprecation
95 * \def NS_DEPRECATED_3_42
96 * Tag for things deprecated in version ns-3.42.
97 */
98#define NS_DEPRECATED_3_42(msg) NS_DEPRECATED("Deprecated in ns-3.42: " msg)
99
100/**
101 * \ingroup deprecation
102 * \def NS_DEPRECATED_3_41
103 * Tag for things deprecated in version ns-3.41.
104 */
105#define NS_DEPRECATED_3_41(msg) NS_DEPRECATED("Deprecated in ns-3.41: " msg)
106
107/**
108 * \ingroup deprecation
109 * \def NS_DEPRECATED_3_40
110 * Tag for things deprecated in version ns-3.40.
111 */
112#define NS_DEPRECATED_3_40(msg) NS_DEPRECATED("Deprecated in ns-3.40: " msg)
113
114#endif /* NS3_DEPRECATED_H */