Clean up javadoc in StateMachine

Fix markup to use <pre> instead of <code> for multiline examples.  Fix
a couple of miscellaneous typos and run-on sentences.

Tested by running `javadoc -d /tmp/jd StateMachine.java` and then viewing
the result in Chrome.

Change-Id: I3d0eee4be4c39a77fa9415f457d3c53bc17d66f1