Fix some Markdown formatting issues

Address miscellaneous issues with Markdown formatting in comments which
are consumed by shocco when generating the online documentation.

Change-Id: I953075cdbddbf1f119c6c7e35f039e2e54b79078
output list of failed files and exit non-zero on failures

We want this script to become part of the gate, so we need to ensure
that failures in the docs are propagated upwards.

Change-Id: Ib286326628003969a0989a65a8f7f452c41eea13