better comments for the service api