improve methods documentation