Fix #1226
Document mangling
Merge pull request #1230 from flaviut/fix1226

Fix 1226 and document associated methods