On Wednesday, 9 June 2021 01:20:23 CEST Frederik Schwarzer wrote: > I would like to ask you to report such documentation to me. We see the > topic come up here and there but it then sometimes sinks into oblivion > again because it was part of a merge request that has then been merged > or so.
Here's a little example of docs and code getting mismatched, and layout issues. It's just something I spotted because today I'm chasing crash bugs in skanlite (the KDE scanner application, for e.g. flatbed scanners). A dependent library is libksane, which is sort-of-maybe-a-framework .. I decided to look on api.kde.org. [[ typing this up, btw, takes way more time than just going out and fixing the documentation issues I've spotted, but that wouldn't illustrate the kind of persistent doc-rot we face; it's also not especially about this one bit of software from the KDE community ]] KSane sources https://invent.kde.org/graphics/libksane KSane api docs https://api.kde.org/libksane/html/index.html ## README.md [[ visible on the api docs front page ]] - dependency information, not one of these matches what's in CMakeLists.txt - "CMake options" weirdly include the `D` which isn't part of the option name - where this could be markdown links, it isn't - formatting of bash command leaks into the documentation page ## KSaneIface - plenty of typos incl "Read, Grean, Blue" colors - (rather a personal bugbear) inconsistent start of docs, sometimes right after /** and sometimes on the next comment line - do we have any standard for indicating boolean return values? Seeing 'true' and 'false' (with single-tick quotes) as return values (and sometimes without the ticks) is .. could be better. It should be noted the API docs are pretty **good**, and that the docs-rot reaches the state of "could be better", not "is terribly wrong"; there's still non-zero effort to put into them and I don't know what's a good way to make everyone spring into action to polish them up. [ade]
signature.asc
Description: This is a digitally signed message part.