[PATCH 1/2] lib: define DEPRECATED macro, document its use.

[David Bremner]

This has been tested with gcc and clang.
---
 devel/STYLE     | 10 ++++++++++
 doc/doxygen.cfg |  2 +-
 lib/notmuch.h   |  2 ++
 3 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/devel/STYLE b/devel/STYLE
index 92de42c..fcd5e99 100644
--- 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 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:
+
+  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 42b6339..c033f34 100644
--- 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 3e326bf..5fb51ba 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -59,6 +59,8 @@ NOTMUCH_BEGIN_DECLS
 #define LIBNOTMUCH_MINOR_VERSION	1
 #define LIBNOTMUCH_MICRO_VERSION	0
 
+#define DEPRECATED(major,minor) \
+    __attribute__ ((deprecated ("function deprecated as of libnotmuch " #major "." #minor)))
 #endif /* __DOXYGEN__ */
 
 /**
-- 
2.1.4