IMP  2.0.1
The Integrative Modeling Platform
deprecation_macros.h
Go to the documentation of this file.
1 /**
2  * \file IMP/base/deprecation_macros.h
3  * \brief Control display of deprecation information.
4  *
5  * Copyright 2007-2013 IMP Inventors. All rights reserved.
6  *
7  */
8 
9 #ifndef IMPBASE_DEPRECATION_MACROS_H
10 #define IMPBASE_DEPRECATION_MACROS_H
11 
12 #include <IMP/base/base_config.h>
13 #include "deprecation.h"
14 #include "log.h"
15 #include "log_macros.h"
16 #include "enums.h"
17 
18 /** \brief Mark the functionality as deprecated. It will print out a message.
19 
20  From time to time, \imp is updated in ways that break backward
21  compatibility. In certain cases we will leave the old functionality
22  in so as not to break existing code which uses \imp. Such code is
23  said to be "deprecated". See \salilab{imp/doc/doxygen/deprecated.html,
24  the deprecated class list} for a list of such classes.
25 
26  Deprecated classes are marked in a variety of ways:
27  - They are listed in the "Deprecated List" in the "Related Pages" tab.
28  - They are noted as deprecated in their documentation.
29  - They print a warning when an instance is constructed or the function
30  is called.
31 
32  The warnings can be turned off using the
33  IMP::base::set_print_deprecation_messages function.
34  \param[in] replacement_classname The class which replaces it.
35 
36  Further, \imp can be built without deprecated code by defining
37  using the \c deprecated=False \c scons argument.
38 
39  You should also use the \deprecated command in the doxygen documentation.
40  */
41 #define IMP_DEPRECATED_OBJECT(replacement_classname) \
42  if (::IMP::base::internal::get_print_deprecation_message(get_name())) { \
43  IMP_WARN(get_name() \
44  << " is deprecated " \
45  << "and should not be used.\nUse " \
46  << #replacement_classname << " instead." << std::endl); \
47  ::IMP::base::internal::set_printed_deprecation_message(get_name(), \
48  true); \
49  }
50 /** \see IMP_DEPRECATED_OBJECT()
51  */
52 #define IMP_DEPRECATED_CLASS(classname, replacement_classname) \
53  if (::IMP::base::internal::get_print_deprecation_message(#classname)) { \
54  IMP_WARN(#classname \
55  << " is deprecated " \
56  << "and should not be used.\nUse " \
57  << #replacement_classname << " instead." << std::endl); \
58  ::IMP::base::internal::set_printed_deprecation_message(#classname, \
59  true); \
60  }
61 /** \see IMP_DEPRECATED_OBJECT()
62  */
63 #define IMP_DEPRECATED_FUNCTION(replacement) \
64  if (::IMP::base::internal::get_print_deprecation_message(__func__)) { \
65  IMP_WARN(__func__ \
66  << " is deprecated " \
67  << "and should not be used.\nUse " \
68  << #replacement << " instead." << std::endl); \
69  ::IMP::base::internal::set_printed_deprecation_message(__func__, \
70  true); \
71  }
72 
73 
74 #if !defined(IMP_SWIG_WRAPPER) && (defined(__GNUC__) || defined(__clang__))
75 #define IMP_DEPRECATED_WARN __attribute__((deprecated))
76 #else
77 /** Produce compiler warnings when the function is called.*/
78 #define IMP_DEPRECATED_WARN
79 #endif
80 
81 #if defined(IMP_DOXYGEN)
82 /** Suppress compiler warnings about a call to a deprecated function.*/
83 #define IMP_DEPRECATED_IGNORE(call) call
84 
85 #elif defined(__GNUC__)
86 
87 // This doesn't work except in 4.7 or so and higher due to a bug in gcc
88 #define IMP_DEPRECATED_IGNORE(call) \
89  IMP_GCC_PUSH_POP( diagnostic push) \
90  IMP_GCC_PRAGMA( diagnostic ignored "-Wdeprecated-declarations") \
91  call; \
92  IMP_GCC_PUSH_POP( diagnostic pop)
93 
94 #elif defined(__clang__)
95 #define IMP_DEPRECATED_IGNORE(call) \
96  IMP_CLANG_PRAGMA( diagnostic push) \
97  IMP_CLANG_PRAGMA( diagnostic ignored "-Wdeprecated") \
98  call; \
99  IMP_CLANG_PRAGMA( diagnostic pop)
100 #else
101 #define IMP_DEPRECATED_IGNORE(call) call
102 #endif
103 
104 #endif /* IMPBASE_DEPRECATION_MACROS_H */