Remove Errors section from var_os docs #109894

fleetingbytes · 2023-04-03T14:10:46Z

Remove Errors section from var_os documentation, fixes #109893

Remove `Errors` section from `var_os` documentation

rustbot · 2023-04-03T14:10:54Z

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @cuviper (or someone else) soon.

Please see the contribution instructions for more information. Namely, in order to ensure the minimum review times lag, PR authors and assigned reviewers should ensure that the review label (S-waiting-on-review and S-waiting-on-author) stays updated, invoking these commands when appropriate:

@rustbot author: the review is finished, PR author should check the comments and take action accordingly
@rustbot review: the author is ready for a review, this PR will be queued again in the reviewer's queue

Noratrieb · 2023-04-03T14:21:52Z

While it can't return an error, it can still return None, so I guess the docs should be changed to mention that instead. (yay, return type consistency between var and var_os :(. )

fleetingbytes · 2023-04-03T14:26:47Z

@Nilstrieb the documentation already mentions that var_os returns None if it is not present or if there is other errors. But additionally it currently says that var_os "returns an error if ..." which that can't be true, since its return type is Option.

ChrisDenton · 2023-04-03T14:33:06Z

Right, the wording should be more like "on Error returns None" and then list the things that might cause it to return None.

I don't think removing the section entirely is a good idea. It contains useful information even if it mixes up the return type.

Re-introduced some of the former errors as situations where `None` is returned.

rustbot · 2023-04-03T14:46:49Z

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

Stabilizing library features
Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
Changing public documentation in ways that create new stability guarantees
Changing observable runtime behavior of library APIs

fleetingbytes · 2023-04-03T14:48:58Z

I don't think removing the section entirely is a good idea. It contains useful information even if it mixes up the return type.

Good point. I have reworded the documentation. The original Errors are now reformulated as situations where None is returned. (The error about invalid Unicode is gone for good, though.)

library/std/src/env.rs

Co-authored-by: León Orell Valerian Liehr <[email protected]>

one is enough

Original `var_os` description said that it _may_ return an error if the value contains `=` or NUL. Let's make no promises on the `None` return value in these situation either, keep it in the [potential mood](https://en.wikipedia.org/wiki/Grammatical_mood#Potential).

cuviper · 2023-04-10T23:56:08Z

library/std/src/env.rs

@@ -236,22 +236,14 @@ fn _var(key: &OsStr) -> Result<String, VarError> {
 }

 /// Fetches the environment variable `key` from the current process, returning
-/// [`None`] if the variable isn't set or there's another error.
+/// [`None`] if the environment variable isn't set. It may return `None` also


Note, the first paragraph is best as a relatively short "title", as that's what will be listed on the module page. Can you break this up?

Further referring to `var_os` as a "function" (like in `var`), rather than "method".

cuviper · 2023-04-11T23:20:30Z

Thanks!

@bors r+ rollup

bors · 2023-04-11T23:20:32Z

📌 Commit 7d26963 has been approved by cuviper

It is now in the queue for this repository.

…mpiler-errors Rollup of 10 pull requests Successful merges: - rust-lang#96971 (Initial support for loongarch64-unknown-linux-gnu) - rust-lang#109894 (Remove Errors section from var_os docs) - rust-lang#110000 (Rename tests/ui/unique to tests/ui/box/unit) - rust-lang#110018 (Pass host linker to compiletest.) - rust-lang#110104 ( Reword the docstring in todo! macro definition, fixing a typo) - rust-lang#110113 (Fix `x test ui --target foo` when download-rustc is enabled) - rust-lang#110126 (Support safe transmute in new solver) - rust-lang#110155 (Fix typos in librustdoc, tools and config files) - rust-lang#110162 (rustdoc: remove redundant expandSection code from main.js) - rust-lang#110173 (kmc-solid: Implement `Socket::read_buf`) Failed merges: r? `@ghost` `@rustbot` modify labels: rollup

The documentation incorrectly stated that std::env::var could return an error for variable names containing '=' or the NUL byte. Copy the correct documentation from var_os. var_os was fixed in Commit 8a7a665, Pull Request rust-lang#109894, which closed Issue rust-lang#109893. This documentation was incorrectly added in commit f2c0f29, which replaced a panic in var_os by returning None, but documented the change as "May error if ...". Reference the specific error values and link to them.

…rkingjubilee doc: std::env::var: Returns None for names with '=' or NUL byte The documentation incorrectly stated that std::env::var could return an error for variable names containing '=' or the NUL byte. Copy the correct documentation from var_os. var_os was fixed in Commit 8a7a665, Pull Request rust-lang#109894, which closed Issue rust-lang#109893. This documentation was incorrectly added in commit f2c0f29, which replaced a panic in var_os by returning None, but documented the change as "May error if ...". Reference the specific error values and link to them.

Rollup merge of rust-lang#128902 - evanj:evan.jones/env-var-doc, r=workingjubilee doc: std::env::var: Returns None for names with '=' or NUL byte The documentation incorrectly stated that std::env::var could return an error for variable names containing '=' or the NUL byte. Copy the correct documentation from var_os. var_os was fixed in Commit 8a7a665, Pull Request rust-lang#109894, which closed Issue rust-lang#109893. This documentation was incorrectly added in commit f2c0f29, which replaced a panic in var_os by returning None, but documented the change as "May error if ...". Reference the specific error values and link to them.

Update env.rs

9f1a3a1

Remove `Errors` section from `var_os` documentation

rustbot assigned cuviper Apr 3, 2023

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Apr 3, 2023

Noratrieb changed the title ~~Update env.rs~~ Remove Errors section from var_os docs Apr 3, 2023

add situation where var_os returns None

c252f0d

Re-introduced some of the former errors as situations where `None` is returned.

fmease reviewed Apr 3, 2023

View reviewed changes

library/std/src/env.rs Outdated Show resolved Hide resolved

fleetingbytes and others added 3 commits April 3, 2023 17:13

remove self-reference in var_os doc

5618c8e

Co-authored-by: León Orell Valerian Liehr <[email protected]>

Remove redundant empty line

a450557

one is enough

cuviper reviewed Apr 10, 2023

View reviewed changes

Break up long first paragraph

7d26963

Further referring to `var_os` as a "function" (like in `var`), rather than "method".

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Apr 11, 2023

compiler-errors mentioned this pull request Apr 12, 2023

Rollup of 10 pull requests #110214

Merged

bors merged commit 8a7a665 into rust-lang:master Apr 12, 2023

rustbot added this to the 1.70.0 milestone Apr 12, 2023

evanj mentioned this pull request Aug 9, 2024

doc: std::env::var: Returns None for names with '=' or NUL byte #128902

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Remove Errors section from var_os docs #109894

Remove Errors section from var_os docs #109894

fleetingbytes commented Apr 3, 2023

rustbot commented Apr 3, 2023

Noratrieb commented Apr 3, 2023

fleetingbytes commented Apr 3, 2023 •

edited

Loading

ChrisDenton commented Apr 3, 2023

rustbot commented Apr 3, 2023

fleetingbytes commented Apr 3, 2023

cuviper Apr 10, 2023

cuviper commented Apr 11, 2023

bors commented Apr 11, 2023

Remove Errors section from var_os docs #109894

Remove Errors section from var_os docs #109894

Conversation

fleetingbytes commented Apr 3, 2023

rustbot commented Apr 3, 2023

Noratrieb commented Apr 3, 2023

fleetingbytes commented Apr 3, 2023 • edited Loading

ChrisDenton commented Apr 3, 2023

rustbot commented Apr 3, 2023

fleetingbytes commented Apr 3, 2023

cuviper Apr 10, 2023

Choose a reason for hiding this comment

cuviper commented Apr 11, 2023

bors commented Apr 11, 2023

fleetingbytes commented Apr 3, 2023 •

edited

Loading