update to actual javadoc comments for api methods

- обновил комментарии для api методов до актуального состояния