GNOME Bugzilla – Bug 744057
Force user to provide replacement API with Deprecated tag
Last modified: 2018-02-08 12:32:26 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.
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]
-- 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.