From 08b7c501acd3d59ba271b8b29828ce69c1d87582 Mon Sep 17 00:00:00 2001 From: Lukas Wagner Date: Tue, 23 Apr 2024 13:51:50 +0200 Subject: [PATCH] notify: endpoints: matcher: improve descriptions for API types proxmox-schema will automatically append text (e.g. 'Can be specified more than once'), so we should end every comment with a '.'. Also copy over some text from PVE docs, since these doc comments will now be visible in the PBS documentation. Signed-off-by: Lukas Wagner Tested-by: Maximiliano Sandoval --- proxmox-notify/src/endpoints/gotify.rs | 6 ++--- proxmox-notify/src/endpoints/sendmail.rs | 15 ++++++++----- proxmox-notify/src/endpoints/smtp.rs | 28 +++++++++++++++--------- proxmox-notify/src/matcher.rs | 18 +++++++-------- 4 files changed, 40 insertions(+), 27 deletions(-) diff --git a/proxmox-notify/src/endpoints/gotify.rs b/proxmox-notify/src/endpoints/gotify.rs index ee8ca514..30ee76aa 100644 --- a/proxmox-notify/src/endpoints/gotify.rs +++ b/proxmox-notify/src/endpoints/gotify.rs @@ -40,12 +40,12 @@ pub(crate) const GOTIFY_TYPENAME: &str = "gotify"; #[serde(rename_all = "kebab-case")] /// Config for Gotify notification endpoints pub struct GotifyConfig { - /// Name of the endpoint + /// Name of the endpoint. #[updater(skip)] pub name: String, - /// Gotify Server URL + /// Gotify Server URL. pub server: String, - /// Comment + /// Comment. #[serde(skip_serializing_if = "Option::is_none")] pub comment: Option, /// Deprecated. diff --git a/proxmox-notify/src/endpoints/sendmail.rs b/proxmox-notify/src/endpoints/sendmail.rs index 47901ef1..da0c0cc7 100644 --- a/proxmox-notify/src/endpoints/sendmail.rs +++ b/proxmox-notify/src/endpoints/sendmail.rs @@ -43,21 +43,26 @@ pub struct SendmailConfig { /// Name of the endpoint #[updater(skip)] pub name: String, - /// Mail recipients + /// Mail address to send a mail to. #[serde(default, skip_serializing_if = "Vec::is_empty")] #[updater(serde(skip_serializing_if = "Option::is_none"))] pub mailto: Vec, - /// Mail recipients + /// Users to send a mail to. The email address of the user + /// will be looked up in users.cfg. #[serde(default, skip_serializing_if = "Vec::is_empty")] #[updater(serde(skip_serializing_if = "Option::is_none"))] pub mailto_user: Vec, - /// `From` address for the mail + /// `From` address for sent E-Mails. + /// If the parameter is not set, the plugin will fall back to the + /// email-from setting from node.cfg (PBS). + /// If that is also not set, the plugin will default to root@$hostname, + /// where $hostname is the hostname of the node. #[serde(skip_serializing_if = "Option::is_none")] pub from_address: Option, - /// Author of the mail + /// Author of the mail. Defaults to 'Proxmox Backup Server ($hostname)' #[serde(skip_serializing_if = "Option::is_none")] pub author: Option, - /// Comment + /// Comment. #[serde(skip_serializing_if = "Option::is_none")] pub comment: Option, /// Deprecated. diff --git a/proxmox-notify/src/endpoints/smtp.rs b/proxmox-notify/src/endpoints/smtp.rs index f04583ae..27afeba5 100644 --- a/proxmox-notify/src/endpoints/smtp.rs +++ b/proxmox-notify/src/endpoints/smtp.rs @@ -66,33 +66,41 @@ pub enum SmtpMode { #[serde(rename_all = "kebab-case")] /// Config for Sendmail notification endpoints pub struct SmtpConfig { - /// Name of the endpoint + /// Name of the endpoint. #[updater(skip)] pub name: String, - /// Host name or IP of the SMTP relay + /// Host name or IP of the SMTP relay. pub server: String, - /// Port to use when connecting to the SMTP relay + /// The port to connect to. + /// If not set, the used port defaults to 25 (insecure), 465 (tls) + /// or 587 (starttls), depending on the value of mode #[serde(skip_serializing_if = "Option::is_none")] pub port: Option, #[serde(skip_serializing_if = "Option::is_none")] pub mode: Option, - /// Username for authentication + /// Username to use during authentication. + /// If no username is set, no authentication will be performed. + /// The PLAIN and LOGIN authentication methods are supported #[serde(skip_serializing_if = "Option::is_none")] pub username: Option, - /// Mail recipients + /// Mail address to send a mail to. #[serde(default, skip_serializing_if = "Vec::is_empty")] #[updater(serde(skip_serializing_if = "Option::is_none"))] pub mailto: Vec, - /// Mail recipients + /// Users to send a mail to. The email address of the user + /// will be looked up in users.cfg. #[serde(default, skip_serializing_if = "Vec::is_empty")] #[updater(serde(skip_serializing_if = "Option::is_none"))] pub mailto_user: Vec, - /// `From` address for the mail + /// `From` address for the mail. + /// SMTP relays might require that this address is owned by the user + /// in order to avoid spoofing. The `From` header in the email will be + /// set to `$author <$from-address>`. pub from_address: String, - /// Author of the mail + /// Author of the mail. Defaults to 'Proxmox Backup Server ($hostname)' #[serde(skip_serializing_if = "Option::is_none")] pub author: Option, - /// Comment + /// Comment. #[serde(skip_serializing_if = "Option::is_none")] pub comment: Option, /// Disable this target. @@ -136,7 +144,7 @@ pub struct SmtpPrivateConfig { /// Name of the endpoint #[updater(skip)] pub name: String, - /// Authentication token + /// The password to use during authentication. #[serde(skip_serializing_if = "Option::is_none")] pub password: Option, } diff --git a/proxmox-notify/src/matcher.rs b/proxmox-notify/src/matcher.rs index 2d303782..986deee5 100644 --- a/proxmox-notify/src/matcher.rs +++ b/proxmox-notify/src/matcher.rs @@ -108,42 +108,42 @@ pub const MATCH_FIELD_ENTRY_SCHEMA: Schema = StringSchema::new("Match metadata f #[serde(rename_all = "kebab-case")] /// Config for Sendmail notification endpoints pub struct MatcherConfig { - /// Name of the matcher + /// Name of the matcher. #[updater(skip)] pub name: String, - /// List of matched metadata fields + /// List of matched metadata fields. #[serde(default, skip_serializing_if = "Vec::is_empty")] #[updater(serde(skip_serializing_if = "Option::is_none"))] pub match_field: Vec, - /// List of matched severity levels + /// List of matched severity levels. #[serde(default, skip_serializing_if = "Vec::is_empty")] #[updater(serde(skip_serializing_if = "Option::is_none"))] pub match_severity: Vec, - /// List of matched severity levels + /// List of matched severity levels. #[serde(default, skip_serializing_if = "Vec::is_empty")] #[updater(serde(skip_serializing_if = "Option::is_none"))] pub match_calendar: Vec, - /// Decide if 'all' or 'any' match statements must match + /// Decide if 'all' or 'any' match statements must match. #[serde(skip_serializing_if = "Option::is_none")] pub mode: Option, - /// Invert match of the whole filter + /// Invert match of the whole filter. #[serde(skip_serializing_if = "Option::is_none")] pub invert_match: Option, - /// Targets to notify + /// Targets to notify. #[serde(default, skip_serializing_if = "Vec::is_empty")] #[updater(serde(skip_serializing_if = "Option::is_none"))] pub target: Vec, - /// Comment + /// Comment. #[serde(skip_serializing_if = "Option::is_none")] pub comment: Option, - /// Disable this matcher + /// Disable this matcher. #[serde(skip_serializing_if = "Option::is_none")] pub disable: Option,