     endpoint = @_currentEndpoint
     @_save(endpoint, body)
 
-  ###*
-   * Delete an existing resource of the _currentEndpoint
-   * If the `id` was provided, the API expects this to be a resource update with given {UpdateAction}
-   * @param {Number} version The current version of the resource
-   * @throws {Error} If version is not given
-   * @return {Promise} A promise, fulfilled with an {Object} or rejected with a {SphereError}
-  ###
+  # Public: Delete an existing resource defined by the `Service`
+  #
+  # version - {Number} The current version of the resource to delete
+  #
+  # Throws an {Error} if `version` is missing
+  #
+  # Returns a {Promise}, fulfilled with an {Object} or rejected with an instance of an {Error}
+  #
+  # Examples
+  #
+  #   service = client.products()
+  #   service.byId('123').delete(2)
   delete: (version) ->
     # TODO: automatically fetch the resource if no version is given?
     # TODO: describe which endpoints support this?

        @_rest.PAGED endpoint, =>
          @_wrapResponse.apply(@, [resolve, reject, originalRequest].concat(_.toArray(arguments)))

  ###*
   * Return a {Promise} for a POST call. It can be overridden for custom logic.
   * @param {String} endpoint The resource endpoint
   * @param {String} payload The body payload as a String
   * @return {Promise} A promise, fulfilled with an {Object} or rejected with a {SphereError}
  ###
  _save: (endpoint, payload) ->
    @_setDefaults()
    @_task.addTask =>

    endpoint = "#{@_currentEndpoint}?version=#{version}"
    @_delete(endpoint)

  # Private: Return a {Promise} for a GET call. It can be overridden for custom logic.
  #
  # endpoint - {String} The resource endpoint
  #
  # Returns a {Promise}, fulfilled with an {Object} or rejected with an instance of an {Error}
  _get: (endpoint) ->
    @_setDefaults()
    @_task.addTask =>
