lib: define NOTMUCH_DEPRECATED macro, document its use.

This has been tested with gcc and clang.

diff --git a/devel/STYLE b/devel/STYLE
index 92de42ccc9ba1847234532a88b58840ab5b0151a..24bd5482a4899b185f923302bb4801177dc6b3ea 100644 (file)
--- a/devel/STYLE
+++ b/devel/STYLE
@@ -93,3 +93,13 @@ libnotmuch conventions
 
 * Code which needs to be accessed from both the CLI and from
   libnotmuch should be factored out into libutil (under util/).
+
+* Deprecated functions should be marked with the NOTMUCH_DEPRECATED
+  macro which generates run time warnings with gcc and clang. In order
+  not to confuse doxygen this should go at the beginning of the
+  declaration like:
+
+  NOTMUCH_DEPRECATED(major,minor) notmuch_status_t notmuch_dwim(void *arg);
+
+  The @deprecated doxygen command can be used to generate markup in
+  the API docs.

diff --git a/doc/doxygen.cfg b/doc/doxygen.cfg
index 42b633948113beb2ccae9368293054fb6c600385..c033f344d3c3780dc0a50a1fc3036f06c354c1ec 100644 (file)
--- a/doc/doxygen.cfg
+++ b/doc/doxygen.cfg
@@ -74,7 +74,7 @@ STRICT_PROTO_MATCHING  = NO
 GENERATE_TODOLIST      = NO
 GENERATE_TESTLIST      = NO
 GENERATE_BUGLIST       = NO
-GENERATE_DEPRECATEDLIST= NO
+GENERATE_DEPRECATEDLIST= YES
 ENABLED_SECTIONS       =
 MAX_INITIALIZER_LINES  = 30
 SHOW_USED_FILES        = NO

diff --git a/lib/notmuch.h b/lib/notmuch.h
index c8edc84dcbd702a3916b6204a6171d786b9956d2..9b5046b423c43963882d7af3c3cfb043786033e9 100644 (file)
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -59,6 +59,8 @@ NOTMUCH_BEGIN_DECLS
 #define LIBNOTMUCH_MINOR_VERSION       2
 #define LIBNOTMUCH_MICRO_VERSION       0
 
+#define NOTMUCH_DEPRECATED(major,minor) \
+    __attribute__ ((deprecated ("function deprecated as of libnotmuch " #major "." #minor)))
 #endif /* __DOXYGEN__ */
 
 /**