WELD-1633 extend.xml documentation fixes

Fixing issues described in the WELD-1633 JIRA and further minor cleanups

uses /* comments */ consistently throughout the chapter instead of // (as the docbook template used doesn't seem to understand // as comments in the code listings