[pve-devel] [PATCH installer 1/2] tree-wide: fix rustdoc warnings

[Christoph Heiss <c.heiss@proxmox.com>]

Mostly URLs, which need to be surrounded by < > to be properly
formatted.

Signed-off-by: Christoph Heiss <c.heiss@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



_______________________________________________
pve-devel mailing list
pve-devel@lists.proxmox.com
https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel