update comments documenting the API