since GLib exposes macros, it basically boils down to detecting:

  G_GNUC_DEPRECATED

and

  G_GNUC_DEPRECATED_FOR(gtk_foo_frobnicate)

especially the latter could be used to also fill the @deprecated annotation.

makes sense.

gtkdoc-scan would need to understand the "G_GNUC_DEPRECATED" attributes. There should be no confusing with the check for deprecation guards.

If someone wants to help, get me a list of example using the attributes, so that I can add a test case for the parser.

Also, does gobject-introspection capture that info (there is some plan to drop gtk-docs parser at some point and reuse the gir files - at least optionally).

we use G_GNUC_DEPRECATED in Clutter (along with the deprecation guards); the form is usually:

  retval_t function_name (argument0_t arg0,
                          argument1_t arg1) G_GNUC_DEPRECATED;

since it's a header-file deprecation; evolution-data-server uses the form:

  G_GNUC_DEPRECATED
  retval_t function_name (argument0_t arg0,
                          argument1_t arg1);

instead.

according to Google codesearch, these two are the most commonly used forms.

http://www.google.com/codesearch?hl=en&lr=&q=G_GNUC_DEPRECATED+lang:c&sbtn=Search

(In reply to comment #1)
> since GLib exposes macros, it basically boils down to detecting:
> 
>   G_GNUC_DEPRECATED
> 
> and
> 
>   G_GNUC_DEPRECATED_FOR(gtk_foo_frobnicate)
> 
> especially the latter could be used to also fill the @deprecated annotation.

Emmanuele, how would you then document what API instead should be used. That is the main purpose of this doc-tag,

(In reply to comment #4)
 
> Emmanuele, how would you then document what API instead should be used. That is
> the main purpose of this doc-tag,

the payload of G_GNUC_DEPRECATED_FOR() is the symbol that should be used instead of the deprecated symbol, e.g.:

  void
  gtk_foo_frobnicate (GtkFoo *foo)
        G_GNUC_DEPRECATED_FOR(gtk_foo_set_frobnication_level);

is the equivalent of:

  Deprecated: Use gtk_foo_set_frobnication_level() instead

(which is the actual compiler output for the warning).

what's missing, sadly, is the version number stating since when the deprecation is valid.

We don't need the version number. I need some logic to map the type of the replacement, but I think its fair enough to assume the same type.

Actually, it turns out we want to be able to define this per-module, a la

#ifdef GTK_ENABLE_DEPRECATION_WARNINGS
#define GTK_DEPRECATED G_GNUC_DEPRECATED
#define GTK_DEPRECATED_FOR(x) G_GNUC_DEPRECATED_FOR(x)
#else
#define GTK_DEPRECATED
#define GTK_DEPRECATED_FOR(x)
#endif

So just going off G_GNUC_DEPRECATED[_FOR] is not good enough, since that is not what gtk-doc is going to see in the headers.

I don't actually think replacing the Deprecated: tag with this macro is that interesting; I would prefer to keep an explicit deprecation note in the docs.

The problems that we need solved with priority here are that gtk-doc refuses to
parse a declaration like

void     g_tree_traverse        (GTree            *tree,
                                 GTraverseFunc     traverse_func,
                                 GTraverseType     traverse_type,
                                 gpointer          user_data) GLIB_DEPRECATED;

because it explicitly looks for only G_GNUC_.* or __attribute__ following a declaration. 

The other problem is that gtk-doc spews a warning every time it sees a deprecated module that doesn't have a deprecation guard around it.

Created attachment 198670 [details] [review]
Ignore more decorators on functions

gtk-doc was explicitly ignoring only G_GNUC_*, which is good enough
for G_GNUC_MALLOC, G_GNUC_PRINTF etc. But for deprecation annotations,
we want to be able to change these on a per-module basis, so we
need to be able to wrap G_GNUC_DEPRECATED in, say, a GTK_DEPRECATED
macro. And it would be good if gtk-doc would not stumble over it.

Review of attachment 198670 [details] [review]:

::: gtkdoc-scan.in
@@ +725,3 @@
         # ') __attribute__ (...);'.
         if ($in_declaration eq 'function') {
+            if ($decl =~ s/\)\s*(G_GNUC_.*|.*DEPRECATED.*|${IGNORE_DECORATORS}\s*|__attribute__\s*\(.*\)\s*)?;.*$//) {

Is that the only place where it is needed?

Created attachment 217304 [details] [review]
gtkdoc-scan: recognise attribute-based deprecations

If we see something that looks like a macro for an attribute-based
deprecation (ie: some string matching /_DEPRECATED/) then mark the next
single declaration as <DEPRECATED/> in the -decl.txt

This patch is a pretty big hack but it seems to work for functions, at least.

I'm not really sure what we can do about macros.  We have a lot of them marked as deprecated but with no way for the compiler to enforce that.  In some ways it's a worse situation than we had before...

Another problem with the current code; it can't handle this:

SOUP_AVAILABLE_IN_2_30
SOUP_DEPRECATED_IN_2_38_FOR (soup_session_prefetch_dns)
void            soup_session_prepare_for_uri  (SoupSession           *session,
					       SoupURI               *uri);

It parses this as a function named SOUP_DEPRECATED_IN_2_38_FOR with a return type of SOUP_AVAILABLE_IN_2_30, and some trailing junk. (Even with an appropriate --ignore-decorators.)

Created attachment 266983 [details]
docs build output from GTK+ master

Dan, the fix for #711598 should help the case you mentioned here. Writing more tests now.

Regarding the warning about the missing deprecation guard, should I just remove it? Any better idea.

Comment on attachment 217304 [details] [review]
gtkdoc-scan: recognise attribute-based deprecations

Thanks for the patch. I added comments and tests and pushed it.

Please disregard my question on the deprecation guards, thats what ryans patch does. Everybody please retest.

Created attachment 267027 [details]
docs build output from GTK+ master (after patch)

Output is much improved! Still a few deprecation guard messages remaining though. Could we try to suppress those too?

I think the remaining deprecation warnings are real, the api has Deprecated: comment entries but no DEPRECATED_FOR attributes or deprecation guards.

One thing that is a bit annoying is:
  DOC   Introspecting gobjects
gtk3-scan.c: In function 'get_object_types':
gtk3-scan.c:26:5: warning: 'gtk_action_get_type' is deprecated (declared at ../../../gtk/deprecated/gtkaction.h:96) [-Wdeprecated-declarations]
     object_types[i++] = gtk_action_get_type ();
     ^
So you need to add -DGDK_DISABLE_DEPRECATION_WARNINGS to GTKDOC_CFLAGS in Makefile.am.

Okay, this is all good now. Closing.