Deprecation

Collaboration diagram for Deprecation:

Files
file	deprecated.h
	NS_DEPRECATED macro definition.

Macros
#define	NS_DEPRECATED(msg)   [[deprecated(msg)]]
	Mark a function as deprecated.
#define	NS_DEPRECATED_3_40(msg)   NS_DEPRECATED("Deprecated in ns-3.40: " msg)
	Tag for things deprecated in version ns-3.40.
#define	NS_DEPRECATED_3_41(msg)   NS_DEPRECATED("Deprecated in ns-3.41: " msg)
	Tag for things deprecated in version ns-3.41.
#define	NS_DEPRECATED_3_42(msg)   NS_DEPRECATED("Deprecated in ns-3.42: " msg)
	Tag for things deprecated in version ns-3.42.

Detailed Description

Macro Definition Documentation

NS_DEPRECATED

#define NS_DEPRECATED

(

msg

)

[[deprecated(msg)]]

Mark a function as deprecated.

Users should expect deprecated features to be removed eventually.

When deprecating a feature, please update the documentation with information for users on how to update their code.

The following snippet shows an example of how to deprecate the function SomethingUseful() in favor of the new function TheNewWay(). Note: in the following snippet, the Doxygen blocks are not following the ns-3 style. This allows the code to be safely embedded in the documentation.

/// Do something useful.
///
/// \deprecated This method will go away in future versions of ns-3.
/// See instead TheNewWay().
NS_DEPRECATED_3_XX("see TheNewWay")
void SomethingUseful();
 
/// Do something more useful.
void TheNewWay();

Please follow these two guidelines to ease future maintenance (primarily the eventual removal of the deprecated code):

1. Please use the versioned form NS_DEPRECATED_3_XX, not the generic NS_DEPRECATED.

2. Typically only the declaration needs to be deprecated,

   NS_DEPRECATED_3_XX("see TheNewWay")
   void SomethingUseful();

   but it's helpful to put the same macro as a comment at the site of the definition, to make it easier to find all the bits which eventually have to be removed:

   // NS_DEPRECATED_3_XX("see TheNewWay")
   void SomethingUseful() { ... }

Note

Sometimes it is necessary to silence a deprecation warning. Even though this is highly discouraged, if necessary it is possible to use:

NS_WARNING_PUSH_DEPRECATED;
// call to a function or class that has been deprecated.
NS_WARNING_POP;

These macros are defined in warnings.h

Parameters

msg	Optional message to add to the compiler warning.

Definition at line 95 of file deprecated.h.

NS_DEPRECATED_3_40

#define NS_DEPRECATED_3_40

(

msg

)

NS_DEPRECATED("Deprecated in ns-3.40: " msg)

Tag for things deprecated in version ns-3.40.

Definition at line 116 of file deprecated.h.

NS_DEPRECATED_3_41

#define NS_DEPRECATED_3_41

(

msg

)

NS_DEPRECATED("Deprecated in ns-3.41: " msg)

Tag for things deprecated in version ns-3.41.

Definition at line 109 of file deprecated.h.

NS_DEPRECATED_3_42

#define NS_DEPRECATED_3_42

(

msg

)

NS_DEPRECATED("Deprecated in ns-3.42: " msg)

Tag for things deprecated in version ns-3.42.

Definition at line 102 of file deprecated.h.