Feature/more docs fixes

SSIA . Just one commit I'm not 100% about, "docs/api: update example recommended usage ..." b737078