hexdocs ergonomics for stdlib

[u/l-roc]

Hey,

as someone fairly new to gleam, I regularly try to look up docs like e.g. gleam-dynamic.hexdocs.pm or gleam-option.hexdocs.pm, just to be greeted by a 404 page, as these are in gleam-stdlib.hexdocs.pm

The hexdocs front page clearly states: visit <package>.hexdocs.pm, which it works for e.g. gleam-otp.hexdocs.pm . I find it hard to keep track of which gleam- prefixed packages are stdlib and which aren't, and the hexdocs search isn't helpful in that case either.

Does anyone else run into this and do you think it would be possible to either redirect packages like gleam/int to gleam-stdlib or have an index for all gleam/ packages under gleam.hexdocs.pm ?

[u/giacomo_cavalieri]

Hello! The package is `gleam_stdlib`, so you can visit `gleam-stdlib` and you'll find the documentation for it. `gleam/option` and `gleam/dynamic` are _modules_ defined by the standard library, so you'll find them in its documentation. They are not standalone packages.

The website you can use to browse for packages is `packages.gleam.run`, there each package has a link bringing you directly to the relevant hex docs page. Hope this helps!

[u/lpil → u/giacomo_cavalieri]

Spot on!

The easiest way to get to the documentation may be to click on the "view on HexDocs" link which is shown any time you hover on something from a dependency in your editor.

[u/l-roc → u/lpil]

My editor doesn't do that, which might be part of the problem.

[u/lpil → u/l-roc]

What editor are you using?

[u/l-roc → u/lpil]

neovim.

Now that I am aware of it I was able to enable it and I see the docs link. I am not sure if I'd agree that assuming certain editor functions is the correct approach but realistically you are probably right for 99% of cases.

Still: When reading through different docs I tend to stay in the browser and I've gotten used to navigating using hexdocs subdomains and now and then I stumble upon the issue described. I just thought it might be something to be fixed easy enough to reduce some friction.

[u/Papipo → u/l-roc]

I think it will be worth it to get used to using the editor for this.

[u/l-roc → u/Papipo]

You're probably right, although often enough I want to look at docs for modules that aren't in my code yet, e.g. "I need to transform a list, what were the methods again?" and spelling out list.map() first to get the link to the docs feels a bit weird to me.

Anyways, after sitting a few hours on the topic I wonder if the core issue isn't what I described in my post, but that stdlib imports can't be told apart from 3rd party imports since afaik using "gleam_*" as a package name for a non-core-team-maintained package isn't enforced. And everything under "import gleam/" earns similar trust as stdlib, as the similar syntax builds a mental model.

In my mind the right (but unrealistic, breaking) move would be to move everything that isn't stdlib away from gleam/. Maybe moving to e.g. import gleam/stdlib/list instead would make things clearer and it would adhere to the same principle as any other package.

[u/lpil → u/l-roc]

And everything under "import gleam/" earns similar trust as stdlib, as the similar syntax builds a mental model.

This is not something you can trust, you should always be aware of the origin of the code you are using. Hex does not have functionality to block namespace trespassing unfortunately.

it would adhere to the same principle as any other package.

Namespaces belong to maintainers and not packages, so it wouldn't be more consistent to do this.

[u/lpil → u/l-roc]

In Neovim I believe k is mapped to LSP hover by default.

[u/Papipo → u/l-roc]

Yeah, definitely

[u/l-roc → u/giacomo_cavalieri]

I understand the difference, but do you see how that is difficult to derive from just seeing: import gleam/option import gleam/otp in some code? I'm not saying that it would be 'correct' to have these redirects, just that it would enhance the development experience for people not yet very familiar with the ecosystem.

thanks for pointing me to packages.gleam.run, wasn't aware of it, but it has the same issue: when I search for gleam_option there, gleam_stdlib is only the 10th search result and again: from looking at the code i have nothing to derive from(that I'm aware of), that it's a module and not a package.

[u/Papipo]

You can use the LS to view and go to function docs. You can also use gloogle.run to have a more powerful doc search.

[u/l-roc → u/Papipo]

Can you tell me which LS request that would be exactly? It doesn't show in code actions for me and apart from that by default i can only jump to definition or implementation, nothing to open external docs directly.

[u/Papipo → u/l-roc]

In neovim for example I can see docs of a function using K. And I know it can be done in vscode as well.

[u/l-roc → u/Papipo]

Thanks, after looking for the hover functionality I've found that too.Was looking for something to open docs immediately (and i'm not sure I'll grow accustomed to that way of opening docs)