docs($httpProvider): add documentation

[corytheboyd]

Add documentation for $httpProvider default values

Closes #6682

[caitp]

put these properties above the actual properties, so that people remember to update them when those properties change =)

[corytheboyd]

👍

[corytheboyd]

Perhaps I am missing something, but there doesn't seem to be an elegant way to document nested attributes of an object:

  /**
   * @ngdoc property
   * @name $httpProvider#defaults
   * @description
   * Default attributes for {@link ng.$http $http} service
   * */
  this.defaults = {
    /**
     * @ngdoc property
     * @name $httpProvider#defaults#headers
     * @description
     * Set default headers for all $http requests. Refer to
     * {@link ng.$http#setting-http-headers $http} for documentation about setting
     * default headers.
     * */
    headers: {
      common: {
        'Accept': 'application/json, text/plain, */*'
      },
      post:   copy(CONTENT_TYPE_APPLICATION_JSON),
      put:    copy(CONTENT_TYPE_APPLICATION_JSON),
      patch:  copy(CONTENT_TYPE_APPLICATION_JSON)
    },
  };

$httpProvider#defaults#headers looks pretty wrong, and doesn't work :P Now that I really think about it, there should be setter functions for all of this stuff:

myAwesomeApp.config('$httpProvider', ['$httpProvider', function($httpProvider) {
  $httpProvider.commonHeaders({ 'Accept': '*/*' });
  $httpProvider.postHeaders(...);
  $httpProvider.putHeaders(...);
  $httpProvider.postHeaders(...);
  $httpProvider.patchHeaders(...);

  $httpProvider.xsrfCookieName('XSRF-TOKEN');
  $httpProvider.xsrfHeaderName('X-XSRF-TOKEN');
}]);

That would be much more work though, I say we just stick to getting these docs updated for now :)

[corytheboyd]

I suppose the nesting could be done like this: http://usejsdoc.org/tags-property.html

I wanted to put documentation on the properties themselves, though, because that is rad.

[caitp]

We don't use jsdoc, per se, although dgeni implements some of jsdoc's stuff in some fashion or other

[caitp]

Hmm, looks like other cases in the tree use this format though, so it's possible that dgeni doesn't have the power to do something smarter.

[corytheboyd]

Maybe we just mimic the docs of a simple provider like $logProvider:

$httpProvider

Use $httpProvider to change the default behavior of the $http service. Refer to the [$http](a fancy URL) service for documentation on overriding the defaults.

Properties

defaults

[corytheboyd]

Could always just fall back to good ol' markdown in the description of defaults to describe the different properties of the object.

[caitp]

Yes, that's what I'm saying. But, TIL there's a bug in the rendering of those... /cc @petebacondarwin compare the rendered page to https://github.com/angular/angular.js/blob/master/src/ng/log.js#L50 --- there are a few things missing.

[corytheboyd]

@caitp Moved the defaults documentation block to where it belongs.