Hi,
On 7/10/21 7:38 PM, Friedrich W. H. Kossebau wrote:
Am Samstag, 10. Juli 2021, 18:00:13 CEST schrieb Frederik Schwarzer:
as mentioned earlier
Any pointers? :)
It was discussed in the weekly BBB meetings a few weeks ago.
I would like to document classes/methods/etc that
are going to be deprecated during KF6 development.
Can you help confused-on-first-read people by explaining what "deprecated
during KF6 development" is referring to? Deprecated during KF5 development and
no longer be available in KF6? Not yet deprecated due to no existing
replacement, but with replacement planned in KF6?
Everything that is marked deprecated when KF6 sees the light of day.
For that I scraped up all the deprecation macros from the frameworks and
edited them to be more unified.
That sounds like duplication of data, and worse, a manual copy of a certain
state, which also needs to be manually maintained to be up-to-date to stay
useful.
In general I am also curious what audience is targeted by the planned
documentation and in which work-flows that documentation should solve which
needs, and what other solutions are there which would not satisfy those needs
well enough?
In general, for API already deprecated now during lifetime of KF5 we are
adding porting notes to the very API itself. Which is also the place as API
consumer I would be hoping for to get all needed information straight in one
go, instead of having to jump to other places, which might even get out of
sync or focus of developers (remember that current online docs of api.kde.org
also only provide docs for latest version (and even the development one, not
just the latest released).
And this is a change to what happened in kdelibs4 times, where most
deprecation happened in the development branches for what became KDE
Frameworks, so there also was no API documentation maintained at the same
time. So copying the approach taken for the KDE Frameworks porting notes would
not be needed here 1:1 for what I understand.
Instead we would need to add documentation for those things which are again
deprecated (well, removed rather) during preparation of KF6, where the
replacement also only will be in KF6, so no-one can port before.
The idea is to have the APIs that are being deprecated now documented
when those APIs (and with it the API docs) are removed.
The audience is everyone who is starting the porting work when KF6 is
already there for some time.
Yes it is manual work. However, since the documentation does not remove
stuff that has been removed from the API, it's a thing of adding newer
deprecation markers, which seems manageable.
Do you disagree?
Cheers,
Frederik
