[BUG #8143] add documentation and minor API change
[BUG #8143] use <code> where appropriate