address most of roc's review comments about documentation - DONTBUILD