update comments on public functions