It's true that the Context.Value method is not in the index of the context package documentation. The index only lists the Context interface. We should investigate if this can or should be improved.

I don't see where this applies in the net package. There is a Dial function in the index. It's listed under type Conn, because it's considered a "constructor" so to speak, given it returns (Conn, error):

The Dialer.Dial method is also in the index:

Can you clarify if I'm misunderstanding your point about the net package?

To me, package level functions shouldn't be indented under anything. I know it doesn't show a receiver for it but my first read is that there's a type called Conn and it has a function called Dial. Also, I understand and agree that it works like a constructor but in a language without formal constructors I wouldn't expect the documentation to be organized like it is a constructor.

Thanks for your feedback.

Putting functions that return a specific type under that type is a feature that has existed for many years now. To make progress here, need to investigate what were the trade-offs considered when choosing to implement this feature.

Another factor is that many Go users are used to the current behavior, so a change would be costly. Any potential benefits of a change need to be weighed against the cost of doing it.

There may be some existing work related to the design of the index on pkg.go.dev (/cc @julieqiu) which can take this issue into account.

Labeling as NeedsInvestigation.

/cc @griesemer @julieqiu

The logic behind net.Dial makes sense eventually, and I believe new go people can figure that out and run with it. But when it comes to context.Value(...), I'm less sure what the reasoning is.

I agree that not including the Context.Value method of the context.Context interface is likely worth spending more time on.

It's worth taking into account that the context package is not very representative of most Go packages. It's very small, and has an interface with many methods that include detailed and nuanced implementation.

Compare it to a package like net/http or io, which has many interfaces that are small and their individual methods are less important. For example, the index for net/http has the Handler interface:

Including its ServeHTTP method in the index may not be as helpful in contrast to the other functions associated with that type.

Similarly, the http.Client struct has many fields, but they may or may not be as helpful to list as its methods.

Putting functions that return a specific type under that type is a feature that has existed for many years now. To make progress here, need to investigate what were the trade-offs considered when choosing to implement this feature.

Another factor is that many Go users are used to the current behavior, so a change would be costly. Any potential benefits of a change need to be weighed against the cost of doing it.

Agreed. As soon as you grok that the "constructor" methods are top of the list under a type in the Index, it becomes very valuable. You look at a type, you can see how to make one and how to use it. I would venture that any intention to change this bears the burden of proof that Gophers at large would find this beneficial.