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 :)

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.

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

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.

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

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

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.

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