Force user to provide replacement API with Deprecated tag
Submitted by Philip Withnall @pwithnall
Link to original bug (#744057)
Description
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.