Skip to content

Format std::env::consts docstrings with markdown backticks #128535

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 17, 2024
Merged

Format std::env::consts docstrings with markdown backticks #128535

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
8c91a7e
Format std::env::consts docstrings
mmvanheusden Aug 2, 2024
f8d8aa6
Add unordered list with possible values for each const
mmvanheusden Aug 15, 2024
0328c86
Refer to other docs
mmvanheusden Aug 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
189 changes: 125 additions & 64 deletions library/std/src/env.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -944,106 +944,167 @@ impl fmt::Debug for ArgsOs {
pub mod consts {
use crate::sys::env::os;

/// A string describing the architecture of the CPU that is currently
/// in use.
/// A string describing the architecture of the CPU that is currently in use.
/// An example value may be: `"x86"`, `"arm"` or `"riscv64"`.
///
/// Some possible values:
/// <details><summary>Full list of possible values</summary>
///
/// - x86
/// - x86_64
/// - arm
/// - aarch64
/// - loongarch64
/// - m68k
/// - csky
/// - mips
/// - mips64
/// - powerpc
/// - powerpc64
/// - riscv64
/// - s390x
/// - sparc64
/// * `"x86"`
/// * `"x86_64"`
/// * `"arm"`
/// * `"aarch64"`
/// * `"m68k"`
/// * `"mips"`
/// * `"mips32r6"`
/// * `"mips64"`
/// * `"mips64r6"`
/// * `"csky"`
/// * `"powerpc"`
/// * `"powerpc64"`
/// * `"riscv32"`
/// * `"riscv64"`
/// * `"s390x"`
/// * `"sparc"`
/// * `"sparc64"`
/// * `"hexagon"`
/// * `"loongarch64"`
///
/// </details>
#[stable(feature = "env", since = "1.0.0")]
pub const ARCH: &str = env!("STD_ENV_ARCH");

/// The family of the operating system. Example value is `unix`.
/// A string describing the family of the operating system.
/// An example value may be: `"unix"`, or `"windows"`.
///
/// This value may be an empty string if the family is unknown.
///
/// <details><summary>Full list of possible values</summary>
///
/// Some possible values:
/// * `"unix"`
/// * `"windows"`
/// * `"itron"`
/// * `""`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is missing "wasm", see:

rust/compiler/rustc_target/src/spec/base/wasm.rs

Line 56 in 2c93fab

families: cvs!["wasm"],

which makes me slightly more uncomfortable about accepting this, because I am noticing how easily this will fall out of sync, yet it claims to be a "full list". hrm.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that is indeed tricky. Maybe I can add a notice that the list might be outdated but that kind of defeats the purpose of the list being there in the first place.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm...

  • maybe we could factor out the lists and reinclude them via #[doc = include_str!("")]? I think we should prefer to autogenerate such lists and while demanding that of you seems silly, that will be easier to set up later if they are already smaller .md files.
  • I think saying "this may be outdated" is useless for the reason you mention, but we could address the temporality of the docs in another way. It could mention that this is the "current full list" inside the <summary></summary> tag. Or even say "the compiled list". :^) Or however you might want to phrase that? Even just between versions, the "actual" full list will grow over time, but docs reflect a snapshot in time.

///
/// - unix
/// - windows
/// </details>
#[stable(feature = "env", since = "1.0.0")]
pub const FAMILY: &str = os::FAMILY;

/// A string describing the specific operating system in use.
/// Example value is `linux`.
/// An example value may be: `"linux"`, or `"freebsd"`.
///
/// Some possible values:
/// <details><summary>Full list of possible values</summary>
///
/// - linux
/// - macos
/// - ios
/// - freebsd
/// - dragonfly
/// - netbsd
/// - openbsd
/// - solaris
/// - android
/// - windows
/// * `"linux"`
/// * `"windows"`
/// * `"macos"`
/// * `"android"`
/// * `"ios"`
/// * `"openbsd"`
/// * `"freebsd"`
/// * `"netbsd"`
/// * `"wasi"`
/// * `"hermit"`
/// * `"aix"`
/// * `"apple"`
/// * `"dragonfly"`
/// * `"emscripten"`
/// * `"espidf"`
/// * `"fortanix"`
/// * `"uefi"`
/// * `"fuchsia"`
/// * `"haiku"`
/// * `"hermit"`
/// * `"watchos"`
/// * `"visionos"`
/// * `"tvos"`
/// * `"horizon"`
/// * `"hurd"`
/// * `"illumos"`
/// * `"l4re"`
/// * `"nto"`
/// * `"redox"`
/// * `"solaris"`
/// * `"solid_asp3`
/// * `"vita"`
/// * `"vxworks"`
/// * `"xous"`
///
/// </details>
#[stable(feature = "env", since = "1.0.0")]
pub const OS: &str = os::OS;

/// Specifies the filename prefix used for shared libraries on this
/// platform. Example value is `lib`.
///
/// Some possible values:
///
/// - lib
/// - `""` (an empty string)
/// Specifies the filename prefix, if any, used for shared libraries on this platform.
/// This is either `"lib"` or an empty string. (`""`).
#[stable(feature = "env", since = "1.0.0")]
pub const DLL_PREFIX: &str = os::DLL_PREFIX;

/// Specifies the filename suffix used for shared libraries on this
/// platform. Example value is `.so`.
/// Specifies the filename suffix, if any, used for shared libraries on this platform.
/// An example value may be: `".so"`, `".elf"`, or `".dll"`.
///
/// <details><summary>Full list of possible values</summary>
///
/// Some possible values:
/// * `".so"`
/// * `".dylib"`
/// * `".dll"`
/// * `".sgxs"`
/// * `".a"`
/// * `".elf"`
/// * `".wasm"`
/// * `""` (an empty string)
///
/// - .so
/// - .dylib
/// - .dll
/// </details>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this one should probably just mention that the list is the same as the list for DLL_EXTENSION

#[stable(feature = "env", since = "1.0.0")]
pub const DLL_SUFFIX: &str = os::DLL_SUFFIX;

/// Specifies the file extension used for shared libraries on this
/// platform that goes after the dot. Example value is `so`.
/// Specifies the file extension, if any, used for shared libraries on this platform that goes after the dot.
/// An example value may be: `"so"`, `"elf"`, or `"dll"`.
///
/// <details><summary>Full list of possible values</summary>
///
/// Some possible values:
/// * `"so"`
/// * `"dylib"`
/// * `"dll"`
/// * `"sgxs"`
/// * `"a"`
/// * `"elf"`
/// * `"wasm"`
/// * `""` (an empty string)
///
/// - so
/// - dylib
/// - dll
/// </details>
#[stable(feature = "env", since = "1.0.0")]
pub const DLL_EXTENSION: &str = os::DLL_EXTENSION;

/// Specifies the filename suffix used for executable binaries on this
/// platform. Example value is `.exe`.
/// Specifies the filename suffix, if any, used for executable binaries on this platform.
/// An example value may be: `".exe"`, or `".efi"`.
///
/// Some possible values:
/// <details><summary>Full list of possible values</summary>
///
/// - .exe
/// - .nexe
/// - .pexe
/// - `""` (an empty string)
/// * `".exe"`
/// * `".efi"`
/// * `".js"`
/// * `".sgxs"`
/// * `".elf"`
/// * `".wasm"`
/// * `""` (an empty string)
///
/// </details>
#[stable(feature = "env", since = "1.0.0")]
pub const EXE_SUFFIX: &str = os::EXE_SUFFIX;

/// Specifies the file extension, if any, used for executable binaries
/// on this platform. Example value is `exe`.
/// Specifies the file extension, if any, used for executable binaries on this platform.
/// An example value may be: `"exe"`, or an empty string (`""`).
///
/// <details><summary>Full list of possible values</summary>
///
/// Some possible values:
/// * `"exe"`
/// * `"efi"`
/// * `"js"`
/// * `"sgxs"`
/// * `"elf"`
/// * `"wasm"`
/// * `""` (an empty string)
///
/// - exe
/// - `""` (an empty string)
/// </details>
#[stable(feature = "env", since = "1.0.0")]
pub const EXE_EXTENSION: &str = os::EXE_EXTENSION;
}
Loading