doc: there is no case that is shown, so something was likely missing …

[tshepang]

…from the change

[rust-highfive]

r? @aturon

(rust_highfive has picked a reviewer for you, use r? to override)

[steveklabnik]

I am confused. It's showing what the value of this constant should be, given that we run the builders on this particular platform.

[tshepang]

Where is it shown that we are running on unix/linux?

[steveklabnik]

That's the idea with these. They're demonstrating the value this constant will have.

[tshepang]

But the constant depends on what platform was used to build the code, right?

[steveklabnik]

That's why it's "in this case". When these docs were built.

[tshepang]

I don't get it. There needs to be more explanation than just "in this case". More importantly, how is that info even important... why would we telling readers that the docs were built on unix/linux. I am also confused.

[steveklabnik]

Yeah, I didn't close it, because if its confusing, we should improve it.

These are string constants. This is intended to be showing the example value of said constant.

On Feb 18, 2016, 16:35 -0500, Tshepang Lekhonkhobenotifications@github.com, wrote:

I don't get it. There needs to be more explanation than just "in this case". More importantly, how is that info even important... why would we telling readers that the docs were built onunix/linux. I am also confused.

—
Reply to this email directly orview it on GitHub(#31762 (comment)).

[MatejLach]

@steveklabnik If I understand @tshepang correctly, this link shows it in context:
https://doc.rust-lang.org/std/env/consts/

I think what @tshepang is saying is that when you look at the docs, it doesn't make sense to say The family of the operating system. In this case, unix. - instead just say 'The family of the operating system.' or something like The family of the operating system. For example unix., because for a windows developer, it would be The family of the operating system. In this case, windows.

[tshepang]

@MatejLach understands me

[steveklabnik]

because for a windows developer, it would be The family of the operating system. In this case, windows.

Yes. This existing text was a compromise; there's no way to directly insert it, so I put in the example from the way that the docs will be displayed officially.

[MatejLach]

@steveklabnik Just to make sure, you're saying that you inserted the In this case, unix. because the docs on the website will be running on a Linux box?
If yes, then I think a wording like for example, unix is better than in this case, unix, since it takes some context inference to deduce what this case actually refers to.

[steveklabnik]

Because the builder that builds the docs is running on a Linux box.

On Feb 18, 2016, 18:55 -0500, Matej Ľachnotifications@github.com, wrote:

@steveklabnik(https://github.com/steveklabnik)Just to make sure, you're saying that you inserted theIn this case, unix.because the docs on the website will be running on a Linux box?

—
Reply to this email directly orview it on GitHub(#31762 (comment)).

[frewsxcv]

For what it's worth, I think the text

In this case, unix.

is confusing since it's not immediately obvious what "this" is referring to. In my opinion, I don't think the existence of that sentence adds much value.

[mitaa]

of the operating system in use

That would align this with the doc comment below, and then it's clear to which operating system this actually refers to.

[tshepang]

Adding "in use" is an improvement, thanks.

[mitaa]

These items / doc-comments are never cfg'd out, so it seems like if one were to build windows documentation the docs would still show in this case unix instead of `in this case `windows

I think the listed possible values are clear enough.

[steveklabnik]

@mitaa yes, that's what I meant by

This existing text was a compromise;

[tshepang]

@steveklabnik have you seen this page https://doc.rust-lang.org/nightly/std/env/consts?

[steveklabnik]

Yes, I have.

[steveklabnik]

So, to be clear, what I want to see in an improvement here is to make sure that we have examples of what this constants look like. This was how I did it; other ways are welcome. I don't want to remove the example, though.

[tshepang]

There is no example in that page. What example are you referring to?

[steveklabnik]

These are constants. This is an example showing the value of said constants.

[tshepang]

You are talking about an example as if it exists...

I don't want to remove the example, though.

[steveklabnik]

The example is the text you are trying to remove in this PR.

[MatejLach]

@tshepang I think you're misunderstanding what @steveklabnik means by an example in this case.
I think what Steve means by an example in this case is the unix.
(Like, an example of an integer constant would be '1' and here a valid example is unix)
@steveklabnik That's why I proposed changing it from In this case, unix to for example, unix
The problem here is clarifying what this means, not the unix example itself.

[ollie27]

There's a list of examples under the "Some possible values:" header. Is that not enough?

[tshepang]

They should be enough, but they don't render here. Maybe a bug in rustdoc?

[mitaa]

No, thats actually intentional. On module pages only short summaries are shown.
The full text is on the page of the const itself.
https://doc.rust-lang.org/nightly/std/env/consts/constant.ARCH.html

[tshepang]

Wow, wasn't even aware those are click-able. Well, that makes the case for this change even stronger, don't you think @steveklabnik?

[tshepang]

@steveklabnik ^

[ranma42]

I agree with @steveklabnik that providing an example value in the short summary is convenient, but I also think that @MatejLach is right: the wording for example would be more clear, especially considered that the examples are not generated based on what environment is building the docs.

Also, ARCH has no example in the short summary, which feels like an inconsistency when reading the https://doc.rust-lang.org/std/env/consts/ page. Would it be ok to add an example for it?

[steveklabnik]

@tshepang sorry, I did not see this since @aturon was the reviewer, not me. Let's fix that:

r? @steveklabnik

the wording for example would be more clear,

Yes, this is what I'd like to see.

Would it be ok to add an example for it?

Yes, though I'm guessing the examples would move into the body, rather than be a summary.

[tshepang]

PR updated

[steveklabnik]

@bors: r+ rollup

[bors]

📌 Commit 8f463ea has been approved by steveklabnik