By separating finding the end of the comment from the end of the action,
we can diagnose malformed comments better.
Also tweak the documentation to make the comment syntax clearer.

Fixes #6022.

R=golang-dev, dsymonds
CC=golang-dev
https://golang.org/cl/12570044