Fix markup-related issues in documentation

This change fixes all markup mistakes in docstrings that lead to
warnings and errors during docs building.

Partial-bug: #1277282
Change-Id: I092a684b7587b802427d57f4292398bfd21deeb1