Added potential TODO around State annotations

https://issues.jboss.org/browse/JBTM-2176
More changes to align with STM documentation.
Fixed typo in comment.
Added example for STM doc to reference.
Added the STM docs to the website building scripts