Fixes to doc-comments to improve layout of generated API documentation

[bkoelman]

QUALITY CHECKLIST

• Changes implemented in code
• Complies with our contributing guidelines
• N/A: Adapted tests
• Documentation updated

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.24%. Comparing base (4962e90) to head (19589a5).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1902   +/-   ##
=======================================
  Coverage   92.24%   92.24%           
=======================================
  Files         437      437           
  Lines       14860    14860           
  Branches     2451     2451           
=======================================
  Hits        13708    13708           
  Misses        709      709           
  Partials      443      443           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.