[pbs-devel] [PATCH proxmox v3 04/42] notify: endpoints: matcher: improve descriptions for API types

[Lukas Wagner]

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 <l.wagner at proxmox.com>
---
 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 ee8ca51..30ee76a 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<String>,
     /// Deprecated.
diff --git a/proxmox-notify/src/endpoints/sendmail.rs b/proxmox-notify/src/endpoints/sendmail.rs
index 47901ef..da0c0cc 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<String>,
-    /// 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<String>,
-    /// `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<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<String>,
-    /// Comment
+    /// Comment.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub comment: Option<String>,
     /// Deprecated.
diff --git a/proxmox-notify/src/endpoints/smtp.rs b/proxmox-notify/src/endpoints/smtp.rs
index f04583a..27afeba 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<u16>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub mode: Option<SmtpMode>,
-    /// 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<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<String>,
-    /// 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<String>,
-    /// `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<String>,
-    /// Comment
+    /// Comment.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub comment: Option<String>,
     /// 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<String>,
 }
diff --git a/proxmox-notify/src/matcher.rs b/proxmox-notify/src/matcher.rs
index 2d30378..986deee 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<FieldMatcher>,
 
-    /// 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<SeverityMatcher>,
 
-    /// 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<CalendarMatcher>,
-    /// 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<MatchModeOperator>,
 
-    /// Invert match of the whole filter
+    /// Invert match of the whole filter.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub invert_match: Option<bool>,
 
-    /// 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<String>,
 
-    /// Comment
+    /// Comment.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub comment: Option<String>,
 
-    /// Disable this matcher
+    /// Disable this matcher.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub disable: Option<bool>,
 
-- 
2.39.2