tweak documentation and usage examples (JBIDE-15483)