Use env::func(), not 'the function env::func' in docs for std::env

[pickfire]

Follow up of #75629

r? @jyn514

[jyn514]

I do wonder whether this makes the docs a little harder to read ... it's idiomatic to use env::var and not var for example. @poliorcetics , what do you think?

[pickfire]

@jyn514 Nice idea, I haven't thought about this since I was focused on clearing things up. Clear! Go, go, go...

[poliorcetics]

I think env::something is usually clearer but here it's the documentation for the module itself so maybe it's ok ?

A tentative plus for env::something because being consistent in docs is important but I could be convinced of the opposite.

[pickfire]

@poliorcetics I think it is better to write stuff that was in the module path so that it is easier to understand from users perspective, so the relative path is understandable there user already know the context when browsing the same page.

[poliorcetics]

After looking at the docs I must say I personally prefer the env::item format but I'm not opposed to the item one either, especially when (like in the linked example) the phrasing makes it clear.

[jyn514]

@pickfire do you mind changing this to use env::var() instead of var()? The changes going from 'the env::var function' to env::var() are still helpful I think, but it's not clear that going from env::var() to var() is.

[pickfire]

@pickfire do you mind changing this to use env::var() instead of var()? The changes going from 'the env::var function' to env::var() are still helpful I think, but it's not clear that going from env::var() to var() is.

Don't I need to add [`var`]: env::var? The main reason I add this is to reduce explicit links so it allows readers from the docs not to need to read the link in text form. Is intra-doc links able to figure out the current module to let us use the current module in front? Like env::var without having to put in explicit link? If yes then I do think that way is good but otherwise I think it results in a similar thing (my original reason is to make reading both html and text better).

[jyn514]

Other way around, you need to add [env::var]: var.

The main reason I add this is to reduce explicit links so it allows readers from the docs not to need to read the link in text form.

I think we should optimize for readers of the HTML first and of the markdown second. Adding the link is not a giant burden, there are already hundreds of links in libstd, and IMO it makes the HTML a lot more clear.

[pickfire]

Other way around, you need to add [env::var]: var.

Why not add the module implicitly since most rust imports consists of xxx::yyy? I do find use xxx quite often, maybe we could do an implicit use xxx in rustdoc?

[jyn514]

Sounds similar to #59039, can you add a comment there? Although see also #73445 which is for crates and not modules.

[pickfire]

Okay, we can leave it aside. @jyn514 how do you think we should proceed with this patch?

[jyn514]

I think if you change var to env::var and similar, it will be good to go. However I'm not comfortable merging it as-is.

[jyn514]

Can you squash the commits? r=me with that done and nit addressed

[pickfire]

How do I squash the commits on the web? I feel like opening another pull request is easier. Hehe

[jyn514]

I'm not aware that you can. I recommend using git locally: git rebase -i master and changing all the pick lines to squash except for the first.

[pickfire]

I'm not aware that you can. I recommend using git locally: git rebase -i master and changing all the pick lines to squash except for the first.

I do know how do do it, just feel lazy to do since I need to delete the branch later on. Anyway, I did it already.

[jyn514]

Now you need to squash again 😆

[jyn514]

@bors r+ rollup

[bors]

📌 Commit 1d017eb has been approved by jyn514