pkg.go.dev: navigation index is confusing

[Markus Heukelom]

The main issue is that most package functions are not actually listed under "Functions". 

For example, I wanted to lookup StripPrefix in the http package. I could not find it in the package documentation function index. It was not there. 

So I looked under Types (maybe I did remember it incorrectly?). It wasn't listed there either. 

But I was quite sure it existed. 

I eventually found it using the Jump-To bar.

So, turns out, the function is actually listed under the type "Handler", probably because it implements that interface. 

Well. Cool.  

That's helpful indeed if you are interested to see which types implement "Handler" (even though the index does not state that "Handler" is an interface so you first wonder 1 minute why "Handler" has types hanging under it instead of methods, but ok).

However, the *primary* use of the index is to *quickly* find that function you're looking for.  That's what indexes are for.    Turns out, it just only lists like half of the functions - if you're lucky.

Another example is the x/net/html package. 

The "Parse" function is arguably the most important function of the whole package. Well - you can only find Parse *under* the Node type, which is by default collapsed.

Another fun example is the documentation for type http.FileSystem. It contains this text:

"See the FileServer function to convert a FileSystem to a Handler." 

Awesome! Let's look up that FileServer function in the index.

Well. It's not there.

No. 

You are expected to be so smart to realise that FileServer of course implements the Handler interface and is therefore only listed under the collapsed Handler type. Maddening.

Proposal: just list all functions in the index please.

NOTE: I admire Go & Go.dev. My exaggerative style is just used to illustrate my point.

NOTE: My apologies if this is not the place for go.dev feedback. Please redirect me.

NOTE: I know that the index in the old package docs also has this structure. It has somewhat the same issue, but at least you could scroll through it a scan for function  names.

 

[Axel Wagner]

On Thu, Sep 2, 2021 at 12:26 PM Markus Heukelom <markus....@gain.pro> wrote:

So, turns out, the function is actually listed under the type "Handler", probably because it implements that interface. 

Because it returns that type. It's a heuristic to find "constructors" of types, which is useful if you know you want that type and want to know how to get one.

That's helpful indeed if you are interested to see which types implement "Handler" (even though the index does not state that "Handler" is an interface so you first wonder 1 minute why "Handler" has types hanging under it instead of methods, but ok).

To be clear, a function doesn't "implement" an interface. Only types do. And there is no association (neither in the language, nor the docs) between a type and the interfaces it implements. The association between the type and its constructors is, however, independent of whether that type is an interface or a concrete type.

However, the *primary* use of the index is to *quickly* find that function you're looking for.  That's what indexes are for. 

I don't agree with the premise that "I want to find the function" is inherently more useful than "I want to see how to get this type". I also wouldn't claim it's *less* useful. Both are very useful, depending on what you want.

Personally, if I already know what function I'm looking for, I use Ctrl+F and my browsers search function instead. And I find it far more often useful to be able to quickly see how I'm intended to construct a certain type (without knowing the name of the function to do so).

 

Another example is the x/net/html package. 

The "Parse" function is arguably the most important function of the whole package. Well - you can only find Parse *under* the Node type, which is by default collapsed.

Another fun example is the documentation for type http.FileSystem. It contains this text:

"See the FileServer function to convert a FileSystem to a Handler." 

Awesome! Let's look up that FileServer function in the index.

Well. It's not there.

No. 

You are expected to be so smart to realise that FileServer of course implements the Handler interface and is therefore only listed under the collapsed Handler type. Maddening.

Proposal: just list all functions in the index please.

NOTE: I admire Go & Go.dev. My exaggerative style is just used to illustrate my point.

NOTE: My apologies if this is not the place for go.dev feedback. Please redirect me.

NOTE: I know that the index in the old package docs also has this structure. It has somewhat the same issue, but at least you could scroll through it a scan for function  names.

 

--
You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/golang-nuts/15cb6bbd-83fc-44f7-a5fc-a922b7112461n%40googlegroups.com.

[Wojciech S. Czarnecki]

Dnia 2021-09-02, o godz. 14:32:05
"'Axel Wagner' via golang-nuts" <golan...@googlegroups.com> napisał(a):

> On Thu, Sep 2, 2021 at 12:26 PM Markus Heukelom <markus....@gain.pro>
> wrote:
>
> > So, turns out, the function is actually listed under the type "Handler",
> > probably because it implements that interface.
> >
>

> It's a heuristic to find "constructors" of types, which is useful
> if you know you want that type and want to know how to get one.

Excuse me?!
Does above sentence implies that the new shiny docs site (pkg.go.dev) heuristics
allow me to find only things I am already intimately familiar with?

Uh. Now I am the more glad I got local godoc fork: https://sr.ht/~sircmpwn/godocs.io/

yw,

--
Wojciech S. Czarnecki
<< ^oo^ >> OHIR-RIPE

[Axel Wagner]

On Fri, Sep 3, 2021 at 12:22 PM Wojciech S. Czarnecki <oh...@fairbe.org> wrote:

Dnia 2021-09-02, o godz. 14:32:05
"'Axel Wagner' via golang-nuts" <golan...@googlegroups.com> napisał(a):

> On Thu, Sep 2, 2021 at 12:26 PM Markus Heukelom <markus....@gain.pro>
> wrote:
>
> > So, turns out, the function is actually listed under the type "Handler",
> > probably because it implements that interface.
> > 
>
> It's a heuristic to find "constructors" of  types, which is useful
> if you know you want that type and want to know how to get one.

Excuse me?!
Does above sentence implies that the new shiny docs site (pkg.go.dev) heuristics
allow me to find only things I am already intimately familiar with?

No. a) quite the contrary, it helps you find things you are *not* familiar with, as I tried to explain.

And b) this is not a property of pkg.go.dev - the old godoc and godoc.org both had the same behavior. 

Uh. Now I am the more glad I got local godoc fork: https://sr.ht/~sircmpwn/godocs.io/

This also behaves the same. Look where StripPrefix is listed here: https://godocs.io/net/http#pkg-index

You obviously are trying to make this about something it is not, just to rile people up. Please don't.

 

yw,

--
Wojciech S. Czarnecki
 << ^oo^ >> OHIR-RIPE

--
You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/golang-nuts/20210903122127.57a89178%40xmint.

[Wojciech S. Czarnecki]

Dnia 2021-09-03, o godz. 12:26:39
Axel Wagner <axel.wa...@googlemail.com> napisał(a):

> And b) this is not a property of pkg.go.dev - the old godoc and godoc.org
> both had the same behavior.

> This also behaves the same. Look where StripPrefix is listed here:

Hm... Yes. My bad, Axel. I should have checked before hitting "send". :(
I misunderstood Markus Heukelom's problem.

@Markus: I normally use browser's search function to get to the function
and it works well with pkg.go.dev too.

@Axel: I sincerely apologize for undeserved and misguided sarcasm. Shame on me.

[Markus Heukelom]

@Markus: I normally use browser's search function to get to the function
and it works well with pkg.go.dev too.

Using the search function only works if you know the name of the function.

Very common examples when this doesn't work:

Package HTTP: 

If you vaguely remember a function name, for example "TrimPrefix" (note: it's actually "StripPrefix"), search obviously doesn't work. But it's impossible to just scan through the list of functions in the index to find "StripPrefix". You have to guess "it probably returns a Handler" or "It probably is a type that implements Handler" and then looking under the type.  But the much simpler use case, just going through a list of functions, is not supported.  Which is difficult and frustrating.

Package x/net/html

The function "Parse" is (arguably) the most important function. But it is not in the function index (but Render() is, adding to the confusion).  Worse, even if you guessed that there should be a function with "Parse" in it,  the word "Parse" is very common in the documentation, so browser search also doesn't work well.

----

I think it will be very useful to have all functions under "Functions" so that you can just scan through it when you need it. 

-Markus

--
You received this message because you are subscribed to a topic in the Google Groups "golang-nuts" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/golang-nuts/8nyrNxX0Oq8/unsubscribe.
To unsubscribe from this group and all its topics, send an email to golang-nuts...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/golang-nuts/20210903131341.2742b5b0%40xmint.

[Wojciech S. Czarnecki]

Dnia 2021-09-03, o godz. 17:45:27
Markus Heukelom <markus....@gain.pro> napisał(a):

> > @Markus: I normally use browser's search function to get to the function
> > and it works well with pkg.go.dev too.

> If you vaguely remember a function name, for example "TrimPrefix" (note:
> it's actually "StripPrefix"), search obviously doesn't work.

It works, highlighting proper places. 57 of them. Just scroll and note highlights.

If you do want really concise form to skim the `go doc` tool output is way to go.
Just grep for a few letters for the hints:

`go doc net/http | grep -i pref`
const TrailerPrefix = "Trailer:"
func StripPrefix(prefix string, h Handler) Handler

`go doc net/http | grep -i pars`
func ParseHTTPVersion(vers string) (major, minor int, ok bool)
func ParseTime(text string) (t time.Time, err error)

Hope this helps,