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

[Maximiliano Sandoval]

Thomas Lamprecht <t.lamprecht at proxmox.com> writes:

> 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>,
>>  }

v2 sent.