add :return: and updates some parameter descriptions in doc texts