[pve-devel] [PATCH installer 1/2] tree-wide: fix rustdoc warnings
Christoph Heiss
c.heiss at proxmox.com
Tue Dec 3 11:15:17 CET 2024
Mostly URLs, which need to be surrounded by < > to be properly
formatted.
Signed-off-by: Christoph Heiss <c.heiss at proxmox.com>
---
proxmox-auto-install-assistant/src/main.rs | 10 +++++----
proxmox-installer-common/src/options.rs | 6 +++---
proxmox-installer-common/src/utils.rs | 23 ++++++++++++++-------
proxmox-post-hook/src/main.rs | 8 +++----
proxmox-tui-installer/src/views/bootdisk.rs | 2 +-
5 files changed, 29 insertions(+), 20 deletions(-)
diff --git a/proxmox-auto-install-assistant/src/main.rs b/proxmox-auto-install-assistant/src/main.rs
index d7aa134..c837cba 100644
--- a/proxmox-auto-install-assistant/src/main.rs
+++ b/proxmox-auto-install-assistant/src/main.rs
@@ -53,10 +53,10 @@ struct CommandDeviceInfo {
/// Test which devices the given filter matches against
///
/// Filters support the following syntax:
-/// ? Match a single character
-/// * Match any number of characters
-/// [a], [0-9] Specific character or range of characters
-/// [!a] Negate a specific character of range
+/// - `?` Match a single character
+/// - `*` Match any number of characters
+/// - `[a]`, `[0-9]` Specific character or range of characters
+/// - `[!a]` Negate a specific character of range
///
/// To avoid globbing characters being interpreted by the shell, use single quotes.
/// Multiple filters can be defined.
@@ -64,7 +64,9 @@ struct CommandDeviceInfo {
/// Examples:
/// Match disks against the serial number and device name, both must match:
///
+/// ```sh
/// proxmox-auto-install-assistant match --filter-match all disk 'ID_SERIAL_SHORT=*2222*' 'DEVNAME=*nvme*'
+/// ```
#[derive(Args, Debug)]
#[command(verbatim_doc_comment)]
struct CommandDeviceMatch {
diff --git a/proxmox-installer-common/src/options.rs b/proxmox-installer-common/src/options.rs
index 37e6260..6ec7d5c 100644
--- a/proxmox-installer-common/src/options.rs
+++ b/proxmox-installer-common/src/options.rs
@@ -463,13 +463,13 @@ impl NetworkOptions {
}
}
-/// Validates an email address using the regex for <input type="email" /> elements
-/// as defined in the HTML specification [0].
+/// Validates an email address using the regex for `<input type="email" />` elements
+/// as defined in the [HTML specification].
/// Using that /should/ cover all possible cases that are encountered in the wild.
///
/// It additionally checks whether the email our default email placeholder value.
///
-/// [0] https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address
+/// [HTML specification]: <https://html.spec.whatwg.org/multipage/input.html#valid-e-mail-address>
pub fn email_validate(email: &str) -> Result<()> {
static RE: OnceLock<Regex> = OnceLock::new();
let re = RE.get_or_init(|| {
diff --git a/proxmox-installer-common/src/utils.rs b/proxmox-installer-common/src/utils.rs
index 2579c80..8686edf 100644
--- a/proxmox-installer-common/src/utils.rs
+++ b/proxmox-installer-common/src/utils.rs
@@ -151,22 +151,29 @@ impl fmt::Display for FqdnParseError {
/// A type for safely representing fully-qualified domain names (FQDNs).
///
/// It considers following RFCs:
-/// https://www.ietf.org/rfc/rfc952.txt (sec. "ASSUMPTIONS", 1.)
-/// https://www.ietf.org/rfc/rfc1035.txt (sec. 2.3. "Conventions")
-/// https://www.ietf.org/rfc/rfc1123.txt (sec. 2.1. "Host Names and Numbers")
-/// https://www.ietf.org/rfc/rfc3492.txt
-/// https://www.ietf.org/rfc/rfc4343.txt
+/// - [RFC952] (sec. "ASSUMPTIONS", 1.)
+/// - [RFC1035] (sec. 2.3. "Conventions")
+/// - [RFC1123] (sec. 2.1. "Host Names and Numbers")
+/// - [RFC3492]
+/// - [RFC4343]
///
/// .. and applies some restriction given by Debian, e.g. 253 instead of 255
-/// maximum total length and maximum 63 characters per label.
-/// https://manpages.debian.org/stable/manpages/hostname.7.en.html
+/// maximum total length and maximum 63 characters per label, per the
+/// [hostname(7)].
///
/// Additionally:
/// - It enforces the restriction as per Bugzilla #1054, in that
/// purely numeric hostnames are not allowed - against RFC1123 sec. 2.1.
///
/// Some terminology:
-/// - "label" - a single part of a FQDN, e.g. <label>.<label>.<tld>
+/// - "label" - a single part of a FQDN, e.g. {label}.{label}.{tld}
+///
+/// [RFC952]: <https://www.ietf.org/rfc/rfc952.txt>
+/// [RFC1035]: <https://www.ietf.org/rfc/rfc1035.txt>
+/// [RFC1123]: <https://www.ietf.org/rfc/rfc1123.txt>
+/// [RFC3492]: <https://www.ietf.org/rfc/rfc3492.txt>
+/// [RFC4343]: <https://www.ietf.org/rfc/rfc4343.txt>
+/// [hostname(7)]: <https://manpages.debian.org/stable/manpages/hostname.7.en.html>
#[derive(Clone, Debug, Eq)]
pub struct Fqdn {
parts: Vec<String>,
diff --git a/proxmox-post-hook/src/main.rs b/proxmox-post-hook/src/main.rs
index da47da9..08a2b90 100644
--- a/proxmox-post-hook/src/main.rs
+++ b/proxmox-post-hook/src/main.rs
@@ -99,7 +99,7 @@ struct ProductInfo {
}
/// The current kernel version.
-/// Aligns with the format as used by the /nodes/<node>/status API of each product.
+/// Aligns with the format as used by the `/nodes/<node>/status` API of each product.
#[derive(Serialize)]
struct KernelVersionInformation {
/// The systemname/nodename
@@ -421,14 +421,14 @@ impl PostHookInfo {
///
/// First, it determines the exact path to the kernel image (aka. `/boot/vmlinuz-<version>`)
/// by looking at the installed kernel package, then reads the string directly from the image
- /// from the well-defined kernel header. See also [0] for details.
- ///
- /// [0] https://www.kernel.org/doc/html/latest/arch/x86/boot.html
+ /// from the [well-defined kernel header].
///
/// # Arguments
///
/// * `run_cmd` - Callback to run a command inside the target chroot.
/// * `open_file` - Callback to open a file inside the target chroot.
+ ///
+ /// [well-defined kernel header]: https://www.kernel.org/doc/html/latest/arch/x86/boot.html
#[cfg(target_arch = "x86_64")]
fn gather_kernel_version(
run_cmd: &dyn Fn(&[&str]) -> Result<String>,
diff --git a/proxmox-tui-installer/src/views/bootdisk.rs b/proxmox-tui-installer/src/views/bootdisk.rs
index 1429984..fffb05e 100644
--- a/proxmox-tui-installer/src/views/bootdisk.rs
+++ b/proxmox-tui-installer/src/views/bootdisk.rs
@@ -30,7 +30,7 @@ use proxmox_installer_common::{
};
/// OpenZFS specifies 64 MiB as the absolute minimum:
-/// https://openzfs.github.io/openzfs-docs/Performance%20and%20Tuning/Module%20Parameters.html#zfs-arc-max
+/// <https://openzfs.github.io/openzfs-docs/Performance%20and%20Tuning/Module%20Parameters.html#zfs-arc-max>
const ZFS_ARC_MIN_SIZE_MIB: usize = 64; // MiB
/// Convenience wrapper when needing to take a (interior-mutable) reference to `BootdiskOptions`.
--
2.47.0
More information about the pve-devel
mailing list