docs($resource): add example for a custom PUT request

Closes #5302

Author: unclejustin

src/ngResource/resource.js

@@ -90,7 +90,7 @@ function shallowClearAndCopy(src, dst) {
  *   when a param value needs to be obtained for a request (unless the param was overridden).
  *
  *   Each key value in the parameter object is first bound to url template if present and then any
- *   excess keys are appended to the url search query after the `?`.
+ *   excess keys are appended to the url seapph query after the `?`.
  *
  *   Given a template `/path/:verb` and parameter `{verb:'greet', salutation:'Hello'}` results in
  *   URL `/path/greet?salutation=Hello`.
@@ -272,6 +272,35 @@ function shallowClearAndCopy(src, dst) {
        });
      });
    </pre>
+
+ * @example
+ * # Creating a custom 'PUT' request
+ * In this example we create a custom method on our resource to make a PUT request
+ 	<pre>
+		var app = angular.module('app', ['ngResource', 'ngRoute']);
+
+		// Some APIs expect a PUT request in the format URL/object/ID
+		// Here we are creating an 'update' method 
+		app.factory('Notes', ['$resource', function($resource) {
+		    return $resource('/notes/:id', null,
+		        {
+		            'update': { method:'PUT' }
+		        });
+		}]);
+
+		// In our controller we get the ID from the URL using ngRoute and $routeParams
+		// We pass in $routeParams and our Notes factory along with $scope
+		app.controller('NotesCtrl', ['$scope', '$routeParams', 'Notes', function($scope, $routeParams, Notes) {
+		    // First get a note object from the factory
+		    var note = Notes.get({ id:$routeParams.id });
+		    $id = note.id;
+
+		    // Now call update passing in the ID first then the object you are updating
+		    Notes.update({ id:$id }, note);
+
+		    // This will PUT /notes/ID with the note object in the request payload
+		}]);
+ 	</pre>
  */
 angular.module('ngResource', ['ng']).
   factory('$resource', ['$http', '$q', function($http, $q) {