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

[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

[PATCH 2/2] lib: deprecate notmuch_query_search_{threads, messages}

[David Bremner]

The CLI (and bindings) code should really be updated to use the new
status-code-returning versions. Here are some warnings to prod us (and
other clients) to do so.
---
 lib/notmuch.h | 41 ++++++++++++++++++++++++++---------------
 1 file changed, 26 insertions(+), 15 deletions(-)

diff --git a/lib/notmuch.h b/lib/notmuch.h
index 5fb51ba..6e4b768 100644
--- a/lib/notmuch.h
+++ b/lib/notmuch.h
@@ -781,20 +781,25 @@ notmuch_query_add_tag_exclude (notmuch_query_t *query, const char *tag);
  * notmuch_threads_destroy function, but there's no good reason
  * to call it if the query is about to be destroyed).
  *
- * If a Xapian exception occurs this function will return NULL.
- * For better error reporting, use the _st variant.
- */
-notmuch_threads_t *
-notmuch_query_search_threads (notmuch_query_t *query);
-
-/**
- * Like notmuch_query_search_threads, but with a status return.
  */
 notmuch_status_t
 notmuch_query_search_threads_st (notmuch_query_t *query,
 				 notmuch_threads_t **out);
 
 /**
+ * Like notmuch_query_search_threads_st, but without a status return.
+ *
+ * If a Xapian exception occurs this function will return NULL.
+ *
+ * @deprecated Deprecated as of libnotmuch 4.2 (notmuch 0.20). Please
+ * use notmuch_query_search_threads_st instead.
+ *
+ */
+DEPRECATED(4,2)
+notmuch_threads_t *
+notmuch_query_search_threads (notmuch_query_t *query);
+
+/**
  * Execute a query for messages, returning a notmuch_messages_t object
  * which can be used to iterate over the results. The returned
  * messages object is owned by the query and as such, will only be
@@ -832,17 +837,23 @@ notmuch_query_search_threads_st (notmuch_query_t *query,
  * reason to call it if the query is about to be destroyed).
  *
  * If a Xapian exception occurs this function will return NULL.
- * For better error reporting, use the _st variant.
- */
-notmuch_messages_t *
-notmuch_query_search_messages (notmuch_query_t *query);
-
-/**
- * Like notmuch_query_search_messages, but with a status return.
+ *
  */
 notmuch_status_t
 notmuch_query_search_messages_st (notmuch_query_t *query,
 				  notmuch_messages_t **out);
+/**
+ * Like notmuch_query_search_messages, but without a status return.
+ *
+ * If a Xapian exception occurs this function will return NULL.
+ *
+ * @deprecated Deprecated as of libnotmuch 4.2 (notmuch 0.20). Please use
+ * notmuch_query_search_messages_st instead.
+ *
+ */
+DEPRECATED(4,2)
+notmuch_messages_t *
+notmuch_query_search_messages (notmuch_query_t *query);
 
 /**
  * Destroy a notmuch_query_t along with any associated resources.
-- 
2.1.4

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

[Jani Nikula]

On Sat, 07 Mar 2015, David Bremner <david@tethera.net> wrote:
> 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) \

Is that perhaps a too generic name for a macro? NOTMUCH_DEPRECATED?

Otherwise seems nice. Did not actually try it.

BR,
Jani.

> +    __attribute__ ((deprecated ("function deprecated as of libnotmuch " #major "." #minor)))
>  #endif /* __DOXYGEN__ */
>  
>  /**
> -- 
> 2.1.4
>
> _______________________________________________
> notmuch mailing list
> notmuch@notmuchmail.org
> http://notmuchmail.org/mailman/listinfo/notmuch