libksane apidocs outdated
Email by Adriaan de Groot
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.