misc documentations and clean ups

@stkem  FYI