GNOME Bugzilla – Bug 744055
Force user to provide replacement API with Deprecated tag
Last modified: 2018-05-22 13:09:36 UTC
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.
See bug #744057 for the corresponding gobject-introspection changes.
> The version and replacement-API would be required. How do you suggest to introduce ‘would be required’ in a backward-compatible manner? If the suggestion is to break all documentation that does not provide the newly required stuff, I'm happy I have not yet switched from --deprecated-guards...
(In reply to comment #2) > > The version and replacement-API would be required. > > How do you suggest to introduce ‘would be required’ in a backward-compatible > manner? It’s a tricky one. I gave one strawman suggestion of introducing it over the course of two release cycles, but it’s not a great suggestion. It could start out as a warning and later be upgraded to an error. Arguably, people’s documentation is broken if they are not providing suggested replacement APIs…but then they might well be providing them in a format which doesn’t match the mandated new syntax. I guess we could go down the route of hiding this behind a -Wbad-deprecations flag, which is enabled by default in the template Makefile.am, so new modules use it but existing ones have to explicitly enable it. We (probably me) then enable it for existing modules as we fix their Deprecated tags.
(In reply to comment #3) > It could start out as a warning and later be upgraded to an error. Still not backward-compatible in my book... I understand if a specific project wants to declare this as documentation policy and gtk-doc can provide an option to make missing replacement API an error. But that is not what was suggested. > Arguably, people’s documentation is broken if they are not providing suggested > replacement APIs… Hardly. The endless stream of deprecation and introduction of new APIs because there is a better way to do something is Gtk+'s malady. It perhaps makes sense to support this development approach but don't think is it a good idea to design a documentation tool around it. A package that only deprecates functions that cannot deliver what they promise (e.g. because assertions about ‘the world’ no longer hold) would have little use for the replacement tag. Actually, it might not have much use for the version either because the deprecation is retroactive in this case: the problem has nothing to do with the package version. > I guess we could go down the route of hiding this behind a -Wbad-deprecations > flag, which is enabled by default in the template Makefile.am, so new modules > use it but existing ones have to explicitly enable it. We (probably me) then > enable it for existing modules as we fix their Deprecated tags. Yes, please.
I think first we need a more flexible mechanism to manage what checks the user would like to enable as warning and what even make fatal. This would projects allow to define their policy and also to cleanup things step by step. In addition one might say that most sanity checking of the content should be in gtkdoc-check. The other gtkdoc tools should mostly complain about syntactical issues. Also checking docs for being not just a stub is tricky as usual. That being said, I welcome a way to ensure decent docs for deprecation tags. Everything that helps developers to keep up with the waves of deprecation (sadly especially from gtk+) is good.
(In reply to comment #4) > Hardly. The endless stream of deprecation and introduction of new APIs because > there is a better way to do something is Gtk+'s malady. It perhaps makes sense > to support this development approach but don't think is it a good idea to > design a documentation tool around it. I am not suggesting we promote the use of the Deprecated tag on more APIs — I’m just trying to ensure that the documentation for APIs which _are_ deprecated at least contains useful information about how people can stop using the deprecated API. It’s entirely up to a project whether they want to endlessly deprecate things. If they deprecate something with a comment “Deprecated: Bad API.” that’s not at all useful to users of the API. If they deprecate it with “Deprecated: x.y: replacement_api: Some concise reason explaining why they thought the deprecation necessary.” that’s more useful. That’s the motivation for this bug; the motivation is _not_ to encourage people to deprecate more APIs. > > I guess we could go down the route of hiding this behind a -Wbad-deprecations > > flag, which is enabled by default in the template Makefile.am, so new modules > > use it but existing ones have to explicitly enable it. We (probably me) then > > enable it for existing modules as we fix their Deprecated tags. > > Yes, please. Let’s go with that then. :-) (In reply to comment #5) > I think first we need a more flexible mechanism to manage what checks the user > would like to enable as warning and what even make fatal. This would projects > allow to define their policy and also to cleanup things step by step. Agreed. Do you have any other warning flags in mind? > In addition one might say that most sanity checking of the content should be in > gtkdoc-check. The other gtkdoc tools should mostly complain about syntactical > issues. Agreed. But at what point do we consider Deprecated tags which don’t follow the format suggested in comment #0 to be syntactically incorrect? > Also checking docs for being not just a stub is tricky as usual. Yeah, that was more a hope than an actual suggestion.
I just run find . -type f -exec grep -o "* Deprecated: [0-9].*" {} \; over my gnome-jhbuild checkout and it is depressing. * Deprecated: 2.22: #GdkImage should not be used anymore. no replacement given * Deprecated: 2.4: This function is obsolete. Use gdk_draw_pixbuf() instead. 'This function is obsolete' is superfluous. * Deprecated: 2.22: This function will be removed in GTK+ 3 really :/ What if we just ensure: Deprecated: version: Description containing a xref'able replacement. This could be done in gtkdoc-check: - check if there is text after the version at all - check that the text contains a link The deprecation is available in the condition attribute, e.g. condition="deprecated:3.10: Use named icon "bar" instead."
(In reply to comment #7) > What if we just ensure: > Deprecated: version: Description containing a xref'able replacement. I think we would be better off requiring the replacement as a separate parameter in the Deprecated line, otherwise examples like > * Deprecated: 2.22: #GdkImage should not be used anymore. will get the wrong replacement.
(In reply to Philip Withnall from comment #0) > 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. Thats a nonstarter. Deprecations come in different sizes and shapes. If all we did was replacing symbols with other symbols that do the same in a 1-1 fashion, that would be pretty pointless. More often than not, symbols are deprecated as part of a larger API rework that needs a porting guide that a) does not fit in a one-line deprecation note and b) should not be repeated for each individual symbol.
(In reply to Matthias Clasen from comment #9) > (In reply to Philip Withnall from comment #0) > > > 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. > > Thats a nonstarter. Deprecations come in different sizes and shapes. If all > we did was replacing symbols with other symbols that do the same in a 1-1 > fashion, that would be pretty pointless. More often than not, symbols are > deprecated as part of a larger API rework that needs a porting guide that a) > does not fit in a one-line deprecation note and b) should not be repeated > for each individual symbol. True. For cases where large APIs are replaced, the replacement-API could link to the relevant new class, or perhaps to the migration guide itself. I suppose that’s moving back towards Stefan’s suggestion of looking for an xref-able replacement in the description (comment #7). Maybe if we went with that, but checked that the xref wasn’t a link back to the same API (or the class it’s contained in)? I guess that would catch most badness without being too offensive. How about that?
(In reply to Philip Withnall from comment #10) > How about that? I don't think you can achieve anything by adding more warnings to gtk-doc... it has been a wall of warnings since forever. Everybody has learned to disregard warnings from gtk-doc, by now.
Matthias, if you just ignore the warnings, you're doing it wrong :) As I said earlier we need to discuss (as a separate ticket) warning management, so that projects and enable warnings the like to get and keep the output tidy.
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #12) > Matthias, if you just ignore the warnings, you're doing it wrong :) Matthias does raise a good point, in that gtk-doc has historically raised a lot of warnings (legitimately or not) and lots of modules have given up on fixing them, possibly because they were indecipherable DocBook warnings. We should try and improve that (but as a separate bug). However, I can’t think of another way of approaching the problem of rubbish deprecation messages without using warnings. Matthias, do you have any suggestions?
I just don't think trying to 'force' people to write 'better' documentation is within the scope of gtk-doc at all.
(In reply to Matthias Clasen from comment #14) > I just don't think trying to 'force' people to write 'better' documentation > is within the scope of gtk-doc at all. As I see it, there is definitely a problem here, and it definitely needs solving: • API deprecations have historically not been documented well enough, leading to people complaining about not knowing the new API they should port to. • We have G_DEPRECATED_FOR, but as you say, there is often not a single function we can point to as the replacement for something, so that isn’t a complete solution. • The only other way deprecations are denoted is in gtk-doc comments. Therefore, gtk-doc has to be part of the solution of improving documentation of deprecations. If you have other suggestions, I am interested. :-) Maybe ‘force’ was the wrong word for me to use. How about ‘guide’? If we go with Stefan’s suggestion from comment #7, we end up extracting more useful information from the Deprecated tag without forcing a new format if we can avoid it.
-- 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/gtk-doc/issues/30.