Rollup merge of rust-lang#128902 - evanj:evan.jones/env-var-doc, r=wo…

…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.

library/std/src/env.rs

@@ -198,13 +198,12 @@ impl fmt::Debug for VarsOs {
 ///
 /// # Errors
 ///
-/// This function will return an error if the environment variable isn't set.
+/// Returns [`VarError::NotPresent`] if:
+/// - The variable is not set.
+/// - The variable's name contains an equal sign or NUL (`'='` or `'\0'`).
 ///
-/// This function may return an error if the environment variable's name contains
-/// the equal sign character (`=`) or the NUL character.
-///
-/// This function will return an error if the environment variable's value is
-/// not valid Unicode. If this is not desired, consider using [`var_os`].
+/// Returns [`VarError::NotUnicode`] if the variable's value is not valid
+/// Unicode. If this is not desired, consider using [`var_os`].
 ///
 /// # Examples
 ///