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 744057 - Force user to provide replacement API with Deprecated tag
Force user to provide replacement API with Deprecated tag
Status: RESOLVED OBSOLETE
Product: gobject-introspection
Classification: Platform
Component: g-ir-scanner
2.43.x
Other All
: Normal enhancement
: ---
Assigned To: gobject-introspection Maintainer(s)
gobject-introspection Maintainer(s)
Depends on:
Blocks:
 
 
Reported: 2015-02-05 17:06 UTC by Philip Withnall
Modified: 2018-02-08 12:32 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Philip Withnall 2015-02-05 17:06:04 UTC
See bug #744055 for the gtk-doc version of this.

It seems to be common for people to use the ‘Deprecated’ tag and just provide a version number. That’s quite unhelpful for anyone reading the documentation for a deprecated function, because they would also like to know what API replaces it, and why it was deprecated in the first place.

I suggest that gtk-doc make its ‘Deprecated’ tag more explicit, with the format:
    Deprecated: version: replacement-API: Description which is a full sentence.

The version and replacement-API would be required. The replacement-API should be the name of another symbol in the documentation, so it can be linked to; or it may be ‘no-replacement’ to explicitly indicate there is no replacement.

The description would also be required. Maybe g-ir-scanner should throw a warning if it’s less than 30 characters long, or something like that? Or is that too strict?

The replacement-API could be exposed as a new attribute in GIR files: how about ‘deprecated-for’?

As in bug #744055, spewing warnings and errors about this is going to break existing modules until they properly document their deprecations. We could start out with a warning, and then upgrade to an error after one cycle. There should be fewer problems with g-ir-scanner than with gtkdoc-scan because developers typically have introspection enabled by default, but don’t have --enable-gtk-doc enabled by default.
Comment 1 André Klapper 2015-02-07 17:16:35 UTC
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]
Comment 2 GNOME Infrastructure Team 2018-02-08 12:32:26 UTC
-- GitLab Migration Automatic Message --

This bug has been migrated to GNOME's GitLab instance and has been closed from further activity.

You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/gobject-introspection/issues/121.