[QGIS-Developer] Deprecated methods in API documentation

[DelazJ]

Hi devs,

Bear with me if this is a dumb question. I'm not aware of best practice in
this area.

Few days ago, we got some failure on test code in the docs and on my way to
fix it, I found out it was due to a deprecated method
QgsVectorFileWriter.writeAsVectorFormatV2 in master. Browsing the PyQGIS
docs website for the new Chosen One, I found in the same page (
https://qgis.org/pyqgis/master/core/QgsVectorFileWriter.html) :
- multiple occurrences of writeAsVectorFormat that are tagged as deprecated
and that we should be using writeAsVectorFormatV2
- writeAsVectorFormatV2 with its description, itself tagged as deprecated
and we should now use writeAsVectorFormatV3
- and description of the current valid writeAsVectorFormatV3 method to use
in master. The new hero!

It looks weird to me to have writeAsVectorFormat, writeAsVectorFormatV2,
writeAsVectorFormatV3 replacing each other in the same (version) doc.... I
guess we have to increment until the next API break but is it common to
keep listing deprecated methods releases after releases? I assume a
deprecated method is one that no longer works in the newer version. If so,
is it worth keeping it in the docs? Couldn't the deprecation information
appear only in the version that deprecates it, and the future docs only
show the new method in use? Am I saying nonsense or is there something we
need to improve to help users easily find their way in the API?

Greetings,
Harrissou
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-developer/attachments/20210420/5d01685d/attachment.html>