(doc) Update comment docs formatting

The docs team can now automatically extract comment docs from facts, but that means that the comment docs have to be formatted just a bit more consistently now. I've also done quite a bit of copy-editing.