$location getters need better documentation

[eheikes]

Am I missing something, or are the return values for some $location getters, specifically protocol() and host(), unclear?

The $location documentation seems vague. The code comments for urlResolve(), which $location uses, says that the protocol includes the colon and the host includes the port, but this is demonstrably untrue.

Another source of confusion is the fact that window.location.protocol includes the colon and window.location.host includes the port as well.

Does $location and urlResolve maybe need improved docs?

[pkozlowski-opensource]

@eheikes hmm, I've got impression that there is some confusion between methods of the $location service that is public and correctly returns host / port part:

it('should correctly parse a host with a protocol', function() {
        url = new LocationHtml5Url('http://host.com:8000/');
        url.$$parse('http://host.com:8000/?a+b=c+d');
        expect(url.host()).toEqual('host.com');
        expect(url.port()).toEqual(8000);
        expect(url.search()).toEqual({'a b':'c d'});
      });

and internal urlResolve function. Indeed if we look at the table https://github.com/angular/angular.js/blob/50e72fcae143ffa9f519a435278a1319e2cdb5c0/src/ng/urlUtils.js#L53-62 and interpret it as a returned value from urlResolve function than indeed, comments for both 'port' and 'host' are invalid. But I've got an impression that this table was more of a comment that should help people reading this code rather than part of the public API documentation.

In short: you shouldn't be looking at the docs for the internal urlResolve function and interpret it as a public API of $location - those are 2 different things.

I would love to clarify the docs to make it crystal clear what is returned from $location but I'm not sure I know how to do it. I mean - $location.host() returns a host name only and $location.port() returns just a port so I'm not sure more info is needed here.

But sure, if you can see how to make it clearer a PR would be awesome!

[btford]

I don't think clarifying the internal API of urlResolve is really too important of an issue.

The docs for $location are correct, insofar as I can tell. I think it might be nice to give examples for each method in $location though.