gh-47: (shared-arena) review fixes

Add comments, update the manual.