documentation + changes suggested by review comments