Drake
drake_deprecated.h
Go to the documentation of this file.
1 #pragma once
2 
3 /** @file
4 Provides a portable macro for use in generating compile-time warnings for
5 use of code that is permitted but discouraged. **/
6 
7 #ifdef DRAKE_DOXYGEN_CXX
8 /** Use `DRAKE_DEPRECATED("message")` to discourage use of particular
9 classes, typedefs, variables, non-static data members, functions, arguments,
10 enumerations, and template specializations. A compile time warning will be
11 issued displaying the given message, preceded by "DRAKE DEPRECATED: ".
12 
13 This is typically used for constructs that have been replaced by something
14 better and it is good practice to suggest the appropriate replacement in the
15 deprecation message. Deprecation warnings are conventionally used to convey to
16 users that a feature they are depending on will be removed in a future release.
17 
18 Usage: @code
19  // Attribute comes *before* declaration of a deprecated function or variable;
20  // no semicolon is allowed.
21  DRAKE_DEPRECATED("f() is slow; use g() instead.")
22  int f(int arg);
23 
24  // Attribute comes *after* struct, class, enum keyword.
25  class DRAKE_DEPRECATED("Use MyNewClass instead.")
26  MyClass {
27  };
28 @endcode
29 
30 This feature is standard in C++14 compilers via the `[[deprecated]]` attribute,
31 and this macro will generate the standard attribute when compiled with a
32 C++14-compliant compiler. **/
33 #define DRAKE_DEPRECATED(message)
34 
35 #else // DRAKE_DOXYGEN_CXX
36 
37 /* C++14 introduces a standard way to mark deprecated declarations. Before
38 that we can use non-standard compiler hacks. */
39 /* Figure out the best form of deprecation for this compiler. */
40 #if __cplusplus >= 201402L
41  /* C++14 */
42  #define DRAKE_DEPRECATED(MSG) [[deprecated("\nDRAKE DEPRECATED: " MSG)]]
43 #else /* gcc or clang */
44  #define DRAKE_DEPRECATED(MSG) \
45  __attribute__((deprecated("\nDRAKE DEPRECATED: " MSG)))
46 #endif
47 
48 #endif // DRAKE_DOXYGEN_CXX