After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 624001 - Support attribute-based method to deprecate symbols
Support attribute-based method to deprecate symbols
Status: RESOLVED FIXED
Product: gtk-doc
Classification: Platform
Component: general
unspecified
Other All
: Normal enhancement
: 1.20
Assigned To: gtk-doc maintainers
gtk-doc maintainers
Depends on:
Blocks: 611692 661335
 
 
Reported: 2010-07-10 03:50 UTC by Javier Jardón (IRC: jjardon)
Modified: 2014-01-29 16:35 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
Ignore more decorators on functions (1.39 KB, patch)
2011-10-09 20:25 UTC, Matthias Clasen
committed Details | Review
gtkdoc-scan: recognise attribute-based deprecations (2.62 KB, patch)
2012-06-26 15:15 UTC, Allison Karlitskaya (desrt)
committed Details | Review
docs build output from GTK+ master (201.29 KB, text/plain)
2014-01-22 16:45 UTC, William Jon McCann
  Details
docs build output from GTK+ master (after patch) (94.91 KB, text/plain)
2014-01-23 08:28 UTC, William Jon McCann
  Details

Description Javier Jardón (IRC: jjardon) 2010-07-10 03:50:28 UTC
This is needed to complete one of the GTK+3 tasks.

The idea is to use attribute((deprecated)) to deprecate symbols.

GLib and GTK+ currently use a cpp-based method of deprecation. Switching to the attribute-based method would have the benefit that it can give warnings, instead of just breaking the build (as the current method) and the warnings can point exactly to the source location of deprecated api usage.

See http://live.gnome.org/GTK+/3.0/Tasks#P13 for more info
Comment 1 Emmanuele Bassi (:ebassi) 2010-07-10 07:43:38 UTC
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.
Comment 2 Stefan Sauer (gstreamer, gtkdoc dev) 2010-07-12 13:17:58 UTC
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).
Comment 3 Emmanuele Bassi (:ebassi) 2010-07-12 13:39:34 UTC
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
Comment 4 Stefan Sauer (gstreamer, gtkdoc dev) 2011-03-29 16:10:50 UTC
(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,
Comment 5 Emmanuele Bassi (:ebassi) 2011-03-29 16:27:53 UTC
(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.
Comment 6 Stefan Sauer (gstreamer, gtkdoc dev) 2011-09-21 14:21:59 UTC
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.
Comment 7 Matthias Clasen 2011-10-09 20:09:07 UTC
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.
Comment 8 Matthias Clasen 2011-10-09 20:14:59 UTC
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.
Comment 9 Matthias Clasen 2011-10-09 20:25:18 UTC
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.
Comment 10 Stefan Sauer (gstreamer, gtkdoc dev) 2011-10-10 15:03:47 UTC
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?
Comment 11 Allison Karlitskaya (desrt) 2012-06-26 15:15:30 UTC
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
Comment 12 Allison Karlitskaya (desrt) 2012-06-26 15:16:19 UTC
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...
Comment 13 Dan Winship 2013-01-03 20:28:41 UTC
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.)
Comment 14 William Jon McCann 2014-01-22 16:45:58 UTC
Created attachment 266983 [details]
docs build output from GTK+ master
Comment 15 Stefan Sauer (gstreamer, gtkdoc dev) 2014-01-22 22:15:02 UTC
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 16 Stefan Sauer (gstreamer, gtkdoc dev) 2014-01-23 08:13:29 UTC
Comment on attachment 217304 [details] [review]
gtkdoc-scan: recognise attribute-based deprecations

Thanks for the patch. I added comments and tests and pushed it.
Comment 17 Stefan Sauer (gstreamer, gtkdoc dev) 2014-01-23 08:14:44 UTC
Please disregard my question on the deprecation guards, thats what ryans patch does. Everybody please retest.
Comment 18 William Jon McCann 2014-01-23 08:28:42 UTC
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?
Comment 19 Stefan Sauer (gstreamer, gtkdoc dev) 2014-01-23 18:52:04 UTC
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.
Comment 20 Stefan Sauer (gstreamer, gtkdoc dev) 2014-01-29 16:35:31 UTC
Okay, this is all good now. Closing.