x/website, x/pkgsite, x/tools/cmd/godoc: context.Context.Value isn't present in index, and comment on ordering of functions that return a type

[coreyog]

Recently I've been working with a developer that's new to go and is using the documentation to get up to speed. There have been a couple things missing from the index of some documentation pages.

For example, https://golang.org/pkg/context has no documentation around (context) Value(key interface{}) interface{}. It's shown in an example and mentioned in the interface under type Context but the function feels too important not to be listed in the index or have its own paragraph detailing it.

There's a similar situation with Dial(network string, address string) (net.Conn, error) in the net package. It's talked about in the overview but missing from the index.

[dmitshur]

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?

[coreyog]

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.

[dmitshur]

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

[coreyog]

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.

[dmitshur]

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.