Force user to provide replacement API with Deprecated tag
Submitted by Philip Withnall
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 gtk-doc should throw a warning if it’s less than 30 characters long, or something like that? Or is that too strict?
This change is going to break existing modules until they properly document their deprecations, and is probably going to annoy people at release time when they build with --enable-gtk-doc for the first time in a while. It might be an idea to add this as a check in gtkdoc-check for one cycle first, before enabling it as a fatal error from gtkdoc-scan.