shared/functions: update comments