Improve introspection annotations

Guido Güntherrequested to merge
guidog/phoc:doc-updates into main

Similar in spirit to what we did for phosh recently.

Merge request reports