Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

docs($resourceProvider): provide info and example for configuring $re… #11910

Closed
wants to merge 1 commit into from
Closed

docs($resourceProvider): provide info and example for configuring $re… #11910

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 80 additions & 0 deletions src/ngResource/resource.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,24 @@ function shallowClearAndCopy(src, dst) {
* <div doc-module-components="ngResource"></div>
*
* See {@link ngResource.$resource `$resource`} for usage.
*
* See {@link ngResource.$resourceProvider `$resourceProvider`} for usage.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Merge these two lines into:

See {@link ngResource.$resource `$resource`} and {@link ngResource.$resourceProvider `$resourceProvider`} for usage.

*/

/**
* @ngdoc provider
* @name $resourceProvider
*
* @description
*
* Use for configuring {@link ngResource.$resource `$resource`} in module configuration phase.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would rather change it to something like:

Use `$resourceProvider` to change the default behavior of the {@link ngResource.$resource `$resource`} service.

(You don't have to mention the configuration phase. It's not specific to this provider and we don't want to mention such stuff in every provider's documentation.)

*
* ## Example
* See {@link ngResource.$resourceProvider#defaults `Properties`} for configuring `ngResource`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This Example section is redundant imo.

*
* ## Dependencies
* Requires {@link ngResource `ngResource`} module to be installed.
*
*/

/**
Expand Down Expand Up @@ -349,6 +367,52 @@ angular.module('ngResource', ['ng']).
provider('$resource', function() {
var provider = this;

/**
* @ngdoc property
* @name $resourceProvider#defaults
* @description
* A configuration object for `$resource` instances.
*
* Properties of this object are initialized with a set of values that satisfies a wide range of use cases.
* User can also choose to override these properties in application configuration phase.
*
* Property `stripTrailingSlashes`, default to true, strips trailing slashes from
* calculated URLs.
*
* Property `actions` is an object that sets up high level methods/aliases on `$resource` object
* based on standard HTTP methods. Users can supply an "actions" object with method aliases that
* comply with alternative conventions.
*
* To add your own set of configurations, set it up like so:
* ```
* angular.module('myApp').config(['resourceProvider', function ($resourceProvider){
*
* // Provide your own set of actions on $resource factory.
* // The following comments are Angular's default actions, which are being
* // replaced by an object that includes a PUT method as shown.
* // { 'get': {method:'GET'},
* // 'save': {method:'POST'},
* // 'query': {method:'GET', isArray:true},
* // 'remove': {method:'DELETE'},
* // 'delete': {method:'DELETE'} };
*
* $resourceProvider.defaults.actions = {
* create:{method: 'POST'},
* save: {method: 'POST'},
* update:{method: 'PUT'},
* get: {method: 'GET'},
* query: {method: 'GET', isArray:true},
* remove: {method: 'DELETE'},
* delete: {method: 'DELETE'}
* };
*
* // Don't strip trailing slashes from calculated URLs.
* // Consult your application server's configuration to work in concert with this setting.
* $resourceProvider.defaults.stripTrailingSlashes = false;
* }]);
* ```
*
*/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you bring this more inline with how $cookiesProvider.defaults are formatted ?

this.defaults = {
// Strip slashes by default
stripTrailingSlashes: true,
Expand All @@ -363,6 +427,22 @@ angular.module('ngResource', ['ng']).
}
};

/**
* @ngdoc method
* @name $resourceProvider#$get
* @description Method used by angular DI system to create a `$resourceProvider` instance.
*
* User applications shouldn't need to call this method directly.
* This shows the fact that {@link ngResource.$resource $resource}
* is a high level service built by leveraging {@link ng.$http $http} service.
*
* @param {Object} $http An instance of {@link ng.$http $http} service.
*
* @param {Object} $q An instance {@link ng.$q $q}, Angular's implementation of deferred API.
*
*
* @returns {Function} A factory function, when invoked, returns a $resource object.
*/
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

$get methods should not be documented. They are idiomatic and kind of private to Angular.
As you mention, they should only be called by the framework itself.

this.$get = ['$http', '$q', function($http, $q) {

var noop = angular.noop,
Expand Down