The IsUnspecified method of IP is designed to report whether the IP is an unspecified IP address from IP addressing architecture point of view. In your example, an empty value of IP is not an unspecified IP address. For what it's worth, an unspecified IP address is used as a source address under certain cases on certain signaling protocols, as a wildcard identifier for exposed APIs, as a default route identifier for some applications, and as an entire IP address space on routing protocols.

I agree that the existing documentation is not kind for users. I guess that the go team welcomes any documentation fixes.

I agree that IsZero() addresses can be used, particularly as a Listen address, but the use case for the IsUnspecified() seems particularly narrow.

I did a quick web search and found just a couple of uses around using IsUnspecified() as a proxy for error detection - just as I mistakenly did - and actually incorrect usage where IsLocal() might have been better.

I guess the primary question is, what problem is IsUnspecified() trying to solve and the secondary question is, what is the correct way to test that an IP contains a valid address?

You almost wonder whether there might be an argument for IsListenable() and IsConnectable() functions.

(Yes, I know I can solve my problem with just a couple of lines of code, but this seems to be a missing piece of functionality that should be of general value to any function getting passed an IP).

In any case, these docs answer nobody's questions:

https://golang.org/pkg/net/#IP.IsUnspecified

IsUnspecified reports whether ip is an unspecified address.

Let's either:

• make the function do what people expect (which maybe we can't do for go1compat reasons, but does anybody use this function?)
• document it.

As I mentioned in the initial post, I found a few code fragments that use the function, but most do so incorrectly. They made the same naive mistake I did of taking the word "specified" literally. That is, something unspecified cannot be used because it has no "specific" value.

That is, I took it to mean whether the address was usable or not.

Given go1compat, the best we can do is document IsUnspecified better and perhaps point the reader to more useful functions.

The sort of things I generally want to know about IP addresses are:

• Can I use it as a source or destination address (ie, will bind() work)
• Can it identify an end-point and is thus worthy of storing in a database

Many of the address-space attributes of IP addresses are well covered (linklocal, multicast, etc) but the aforementioned "application" layer semantics are not. So maybe the right approach is to think about this in terms of application layer semantics and then see what we end up with?

aforementioned "application" layer semantics are not.

Yup, the same as #11772. I'll update the existing docs for clarification.

CL https://golang.org/cl/44910 mentions this issue.