Progress is good for us but bad for documentation

[Adriaan de Groot]

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]
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 659 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20210614/84792124/attachment.sig>