some doc comment improvements (closes #10)