[pdm-devel] [PATCH proxmox-api-types] docs: escape HTML delimiters

[Thomas Lamprecht]

Am 14.01.25 um 10:48 schrieb Maximiliano Sandoval:
> Fixes:
> 
> $ cargo doc --all-features --workspace
> warning: unresolved link to `acdn`
>     --> pve-api-types/src/types/../generated/types.rs:3780:5
>      |
> 3780 | /     /// The guest will attempt to boot from devices in the order they appear
> 3781 | |     /// here.
> 3782 | |     ///
> 3783 | |     /// Disks, optical drives and passed-through storage USB devices will be
> ...    |
> 3792 | |     ///
> 3793 | |     /// Overrides the deprecated 'legacy=[acdn]*' value when given.
>      | |___________________________________________________________________^
>      |
>      = note: the link appears in this line:
> 
>              Overrides the deprecated 'legacy=[acdn]*' value when given.
>                                                ^^^^
>      = note: no item named `acdn` in scope
>      = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
>      = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default
> 
> warning: unclosed HTML tag `nodename`
>    --> pve-api-types/src/types/../generated/types.rs:272:5
>     |
> 272 | /     /// Unique identifier for this metric object, for instance 'node/<nodename>'
> 273 | |     /// or 'qemu/<vmid>'.
>     | |_________________________^
>     |
>     = note: `#[warn(rustdoc::invalid_html_tags)]` on by default
> 
> warning: unclosed HTML tag `vmid`
>    --> pve-api-types/src/types/../generated/types.rs:272:5
>     |
> 272 | /     /// Unique identifier for this metric object, for instance 'node/<nodename>'
> 273 | |     /// or 'qemu/<vmid>'.
>     | |_________________________^
> 
> warning: unclosed HTML tag `ostype`
>     --> pve-api-types/src/types/../generated/types.rs:2061:1
>      |
> 2061 | / /// OS type. This is used to setup configuration inside the container, and
> 2062 | | /// corresponds to lxc setup scripts in
> 2063 | | /// /usr/share/lxc/config/<ostype>.common.conf. Value 'unmanaged' can be used to
> 2064 | | /// skip and OS specific setup.
>      | |_______________________________^
> 
> warning: unclosed HTML tag `type`
>   --> pve-api-types/src/client/mod.rs:35:10
>    |
> 35 | /// For "<type>-list" entries we turn an array into a string ready for perl's `split_list()` call.

tbh. I'm not a big fan of having the full error output in the commit message
for these type of commits, this is a lot of noise without much extra value.
Should be enough to just list the warning names it fixes, maybe with the short
description.

One can then check the full error for oneself by compiling the state before this,
or search for the warning name to get all details.

> 
> Signed-off-by: Maximiliano Sandoval <m.sandoval at proxmox.com>
> ---
>  pve-api-types/src/client/mod.rs      | 2 +-
>  pve-api-types/src/generated/types.rs | 8 ++++----
>  2 files changed, 5 insertions(+), 5 deletions(-)
> 
> diff --git a/pve-api-types/src/client/mod.rs b/pve-api-types/src/client/mod.rs
> index 8832272..0de7cc3 100644
> --- a/pve-api-types/src/client/mod.rs
> +++ b/pve-api-types/src/client/mod.rs
> @@ -32,7 +32,7 @@ pub fn add_query_bool(query: &mut String, separator: &mut char, name: &str, valu
>      }
>  }
>  
> -/// For "<type>-list" entries we turn an array into a string ready for perl's `split_list()` call.
> +/// For `<type>-list` entries we turn an array into a string ready for perl's `split_list()` call.

this hunks seems all right, but the ones below are in generated code, so was the source
that produced this error updated already and this is only refreshing the generated code
or  is that still missing?

>  pub fn add_query_arg_string_list<T>(
>      query: &mut String,
>      separator: &mut char,
> diff --git a/pve-api-types/src/generated/types.rs b/pve-api-types/src/generated/types.rs
> index b6a3d20..0532dc6 100644
> --- a/pve-api-types/src/generated/types.rs
> +++ b/pve-api-types/src/generated/types.rs
> @@ -269,8 +269,8 @@ pub struct ClusterMetrics {
>  /// Object.
>  #[derive(Debug, serde::Deserialize, serde::Serialize)]
>  pub struct ClusterMetricsData {
> -    /// Unique identifier for this metric object, for instance 'node/<nodename>'
> -    /// or 'qemu/<vmid>'.
> +    /// Unique identifier for this metric object, for instance `node/<nodename>`
> +    /// or `qemu/<vmid>`.
>      pub id: String,
>  
>      /// Name of the metric.
> @@ -2174,7 +2174,7 @@ serde_plain::derive_fromstr_from_deserialize!(LxcConfigNetType);
>  #[api]
>  /// OS type. This is used to setup configuration inside the container, and
>  /// corresponds to lxc setup scripts in
> -/// /usr/share/lxc/config/<ostype>.common.conf. Value 'unmanaged' can be used to
> +/// `/usr/share/lxc/config/<ostype>.common.conf`. Value 'unmanaged' can be used to
>  /// skip and OS specific setup.
>  #[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Deserialize, serde::Serialize)]
>  pub enum LxcConfigOstype {
> @@ -3910,7 +3910,7 @@ pub struct PveQmBoot {
>      /// disks for booting (e.g. software-raid), you need to specify all of
>      /// them here.
>      ///
> -    /// Overrides the deprecated 'legacy=[acdn]*' value when given.
> +    /// Overrides the deprecated `legacy=[acdn]*` value when given.
>      #[serde(default, skip_serializing_if = "Option::is_none")]
>      pub order: Option<String>,
>  }