docs(external): fix wording in common sinks components docs

Updates wording in common sinks component docs (as suggested by @neko-dd)

Related: #22213 (comment)

Author: esensar

lib/codecs/src/encoding/format/cef.rs

@@ -195,7 +195,7 @@ impl std::fmt::Display for Version {
 #[derive(Debug, Clone)]
 pub struct CefSerializerOptions {
     /// CEF Version. Can be either 0 or 1.
-    /// Equals to "0" by default.
+    /// Set to "0" by default.
     pub version: Version,
 
     /// Identifies the vendor of the product.
@@ -208,7 +208,7 @@ pub struct CefSerializerOptions {
     /// The value length must be less than or equal to 63.
     pub device_product: String,
 
-    /// Identifies the version of the problem. In combination with device product and vendor, it composes the unique id of the device that sends messages.
+    /// Identifies the version of the problem. The combination of the device product, vendor and this value make up the unique id of the device that sends messages.
     /// The value length must be less than or equal to 31.
     pub device_version: String,
 
@@ -220,8 +220,8 @@ pub struct CefSerializerOptions {
     /// Reflects importance of the event.
     ///
     /// It must point to a number from 0 to 10.
-    /// 0 = Lowest, 10 = Highest.
-    /// Equals to "cef.severity" by default.
+    /// 0 = lowest_importance, 10 = highest_importance.
+    /// Set to "cef.severity" by default.
     pub severity: ConfigTargetPath,
 
     /// This is a path that points to the human-readable description of a log event.

lib/codecs/src/encoding/format/csv.rs

@@ -27,8 +27,8 @@ pub enum QuoteStyle {
     Necessary,
 
     /// Puts quotes around all fields that are non-numeric.
-    /// Namely, when writing a field that does not parse as a valid float or integer,
-    /// then quotes are used even if they aren't strictly necessary.
+    /// This means that when writing a field that does not parse as a valid float or integer,
+    /// quotes are used even if they aren't strictly necessary.
     NonNumeric,
 
     /// Never writes quotes, even if it produces invalid CSV data.
@@ -84,9 +84,9 @@ pub struct CsvSerializerOptions {
     )]
     pub delimiter: u8,
 
-    /// Enable double quote escapes.
+    /// Enables double quote escapes.
     ///
-    /// This is enabled by default, but it may be disabled. When disabled, quotes in
+    /// This is enabled by default, but you can disable it. When disabled, quotes in
     /// field data are escaped instead of doubled.
     #[serde(
         default = "default_double_quote",
@@ -99,7 +99,7 @@ pub struct CsvSerializerOptions {
     /// In some variants of CSV, quotes are escaped using a special escape character
     /// like \ (instead of escaping quotes by doubling them).
     ///
-    /// To use this, `double_quotes` needs to be disabled as well otherwise it is ignored.
+    /// To use this, `double_quotes` needs to be disabled as well; otherwise, this setting is ignored.
     #[configurable(metadata(docs::type_override = "ascii_char"))]
     #[serde(
         default = "default_escape",
@@ -121,18 +121,18 @@ pub struct CsvSerializerOptions {
     #[serde(default, skip_serializing_if = "vector_core::serde::is_default")]
     pub quote_style: QuoteStyle,
 
-    /// Set the capacity (in bytes) of the internal buffer used in the CSV writer.
-    /// This defaults to a reasonable setting.
+    /// Sets the capacity (in bytes) of the internal buffer used in the CSV writer.
+    /// This defaults to 8KB.
     #[serde(default = "default_capacity")]
     pub capacity: usize,
 
-    /// Configures the fields that will be encoded, as well as the order in which they
+    /// Configures the fields that are encoded, as well as the order in which they
     /// appear in the output.
     ///
-    /// If a field is not present in the event, the output will be an empty string.
+    /// If a field is not present in the event, the output for that field is an empty string.
     ///
-    /// Values of type `Array`, `Object`, and `Regex` are not supported and the
-    /// output will be an empty string.
+    /// Values of type `Array`, `Object`, and `Regex` are not supported, and the
+    /// output for any of these types is an empty string.
     pub fields: Vec<ConfigTargetPath>,
 }
 

lib/codecs/src/encoding/mod.rs

@@ -206,11 +206,11 @@ pub enum SerializerConfig {
     /// Vector's encoder currently adheres more strictly to the GELF spec, with
     /// the exception that some characters such as `@`  are allowed in field names.
     ///
-    /// Other GELF codecs such as Loki's, use a [Go SDK][implementation] that is maintained
-    /// by Graylog, and is much more relaxed than the GELF spec.
+    /// Other GELF codecs, such as Loki's, use a [Go SDK][implementation] that is maintained
+    /// by Graylog and is much more relaxed than the GELF spec.
     ///
     /// Going forward, Vector will use that [Go SDK][implementation] as the reference implementation, which means
-    /// the codec may continue to relax the enforcement of specification.
+    /// the codec might continue to relax the enforcement of the specification.
     ///
     /// [gelf]: https://docs.graylog.org/docs/gelf
     /// [implementation]: https://github.com/Graylog2/go-gelf/blob/v2/gelf/reader.go

lib/vector-core/src/config/mod.rs

@@ -357,9 +357,9 @@ impl From<SourceAcknowledgementsConfig> for AcknowledgementsConfig {
 pub struct AcknowledgementsConfig {
     /// Whether or not end-to-end acknowledgements are enabled.
     ///
-    /// When enabled for a sink, any source connected to that sink where the source supports
-    /// end-to-end acknowledgements as well, waits for events to be acknowledged by **all
-    /// connected** sinks before acknowledging them at the source.
+    /// When enabled for a sink, any source that supports end-to-end
+    /// acknowledgements that is connected to that sink waits for events
+    /// to be acknowledged by **all connected sinks** before acknowledging them at the source.
     ///
     /// Enabling or disabling acknowledgements at the sink level takes precedence over any global
     /// [`acknowledgements`][global_acks] configuration.

lib/vector-core/src/tls/settings.rs

@@ -92,7 +92,7 @@ pub struct TlsConfig {
     /// If enabled, certificates must not be expired and must be issued by a trusted
     /// issuer. This verification operates in a hierarchical manner, checking that the leaf certificate (the
     /// certificate presented by the client/server) is not only valid, but that the issuer of that certificate is also valid, and
-    /// so on until the verification process reaches a root certificate.
+    /// so on, until the verification process reaches a root certificate.
     ///
     /// Do NOT set this to `false` unless you understand the risks of not verifying the validity of certificates.
     pub verify_certificate: Option<bool>,
@@ -109,7 +109,7 @@ pub struct TlsConfig {
 
     /// Sets the list of supported ALPN protocols.
     ///
-    /// Declare the supported ALPN protocols, which are used during negotiation with peer. They are prioritized in the order
+    /// Declare the supported ALPN protocols, which are used during negotiation with a peer. They are prioritized in the order
     /// that they are defined.
     #[configurable(metadata(docs::examples = "h2"))]
     pub alpn_protocols: Option<Vec<String>>,
@@ -127,7 +127,7 @@ pub struct TlsConfig {
     /// The certificate must be in DER, PEM (X.509), or PKCS#12 format. Additionally, the certificate can be provided as
     /// an inline string in PEM format.
     ///
-    /// If this is set, and is not a PKCS#12 archive, `key_file` must also be set.
+    /// If this is set _and_ is not a PKCS#12 archive, `key_file` must also be set.
     #[serde(alias = "crt_path")]
     #[configurable(metadata(docs::examples = "/path/to/host_certificate.crt"))]
     #[configurable(metadata(docs::human_name = "Certificate File Path"))]

src/transforms/metric_to_log.rs

@@ -54,7 +54,7 @@ pub struct MetricToLogConfig {
 
     /// Controls how metric tag values are encoded.
     ///
-    /// When set to `single`, only the last non-bare value of tags are displayed with the
+    /// When set to `single`, only the last non-bare value of tags is displayed with the
     /// metric.  When set to `full`, all metric tags are exposed as separate assignments as
     /// described by [the `native_json` codec][vector_native_json].
     ///

website/cue/reference/components/sinks/base/amqp.cue

@@ -14,9 +14,9 @@ base: components: sinks: amqp: configuration: {
 			description: """
 				Whether or not end-to-end acknowledgements are enabled.
 
-				When enabled for a sink, any source connected to that sink where the source supports
-				end-to-end acknowledgements as well, waits for events to be acknowledged by **all
-				connected** sinks before acknowledging them at the source.
+				When enabled for a sink, any source that supports end-to-end
+				acknowledgements that is connected to that sink waits for events
+				to be acknowledged by **all connected sinks** before acknowledging them at the source.
 
 				Enabling or disabling acknowledgements at the sink level takes precedence over any global
 				[`acknowledgements`][global_acks] configuration.
@@ -90,7 +90,7 @@ base: components: sinks: amqp: configuration: {
 					}
 					device_version: {
 						description: """
-																Identifies the version of the problem. In combination with device product and vendor, it composes the unique id of the device that sends messages.
+																Identifies the version of the problem. The combination of the device product, vendor and this value make up the unique id of the device that sends messages.
 																The value length must be less than or equal to 31.
 																"""
 						required: true
@@ -123,16 +123,16 @@ base: components: sinks: amqp: configuration: {
 																Reflects importance of the event.
 
 																It must point to a number from 0 to 10.
-																0 = Lowest, 10 = Highest.
-																Equals to "cef.severity" by default.
+																0 = lowest_importance, 10 = highest_importance.
+																Set to "cef.severity" by default.
 																"""
 						required: true
 						type: string: {}
 					}
 					version: {
 						description: """
 																CEF Version. Can be either 0 or 1.
-																Equals to "0" by default.
+																Set to "0" by default.
 																"""
 						required: true
 						type: string: enum: {
@@ -166,11 +166,11 @@ base: components: sinks: amqp: configuration: {
 						Vector's encoder currently adheres more strictly to the GELF spec, with
 						the exception that some characters such as `@`  are allowed in field names.
 
-						Other GELF codecs such as Loki's, use a [Go SDK][implementation] that is maintained
-						by Graylog, and is much more relaxed than the GELF spec.
+						Other GELF codecs, such as Loki's, use a [Go SDK][implementation] that is maintained
+						by Graylog and is much more relaxed than the GELF spec.
 
 						Going forward, Vector will use that [Go SDK][implementation] as the reference implementation, which means
-						the codec may continue to relax the enforcement of specification.
+						the codec might continue to relax the enforcement of the specification.
 
 						[gelf]: https://docs.graylog.org/docs/gelf
 						[implementation]: https://github.com/Graylog2/go-gelf/blob/v2/gelf/reader.go
@@ -234,8 +234,8 @@ base: components: sinks: amqp: configuration: {
 				type: object: options: {
 					capacity: {
 						description: """
-																Set the capacity (in bytes) of the internal buffer used in the CSV writer.
-																This defaults to a reasonable setting.
+																Sets the capacity (in bytes) of the internal buffer used in the CSV writer.
+																This defaults to 8KB.
 																"""
 						required: false
 						type: uint: default: 8192
@@ -247,9 +247,9 @@ base: components: sinks: amqp: configuration: {
 					}
 					double_quote: {
 						description: """
-																Enable double quote escapes.
+																Enables double quote escapes.
 
-																This is enabled by default, but it may be disabled. When disabled, quotes in
+																This is enabled by default, but you can disable it. When disabled, quotes in
 																field data are escaped instead of doubled.
 																"""
 						required: false
@@ -262,20 +262,20 @@ base: components: sinks: amqp: configuration: {
 																In some variants of CSV, quotes are escaped using a special escape character
 																like \\ (instead of escaping quotes by doubling them).
 
-																To use this, `double_quotes` needs to be disabled as well otherwise it is ignored.
+																To use this, `double_quotes` needs to be disabled as well; otherwise, this setting is ignored.
 																"""
 						required: false
 						type: ascii_char: default: "\""
 					}
 					fields: {
 						description: """
-																Configures the fields that will be encoded, as well as the order in which they
+																Configures the fields that are encoded, as well as the order in which they
 																appear in the output.
 
-																If a field is not present in the event, the output will be an empty string.
+																If a field is not present in the event, the output for that field is an empty string.
 
-																Values of type `Array`, `Object`, and `Regex` are not supported and the
-																output will be an empty string.
+																Values of type `Array`, `Object`, and `Regex` are not supported, and the
+																output for any of these types is an empty string.
 																"""
 						required: true
 						type: array: items: type: string: {}
@@ -301,8 +301,8 @@ base: components: sinks: amqp: configuration: {
 								never: "Never writes quotes, even if it produces invalid CSV data."
 								non_numeric: """
 																			Puts quotes around all fields that are non-numeric.
-																			Namely, when writing a field that does not parse as a valid float or integer,
-																			then quotes are used even if they aren't strictly necessary.
+																			This means that when writing a field that does not parse as a valid float or integer,
+																			quotes are used even if they aren't strictly necessary.
 																			"""
 							}
 						}
@@ -430,7 +430,7 @@ base: components: sinks: amqp: configuration: {
 				description: """
 					Sets the list of supported ALPN protocols.
 
-					Declare the supported ALPN protocols, which are used during negotiation with peer. They are prioritized in the order
+					Declare the supported ALPN protocols, which are used during negotiation with a peer. They are prioritized in the order
 					that they are defined.
 					"""
 				required: false
@@ -452,7 +452,7 @@ base: components: sinks: amqp: configuration: {
 					The certificate must be in DER, PEM (X.509), or PKCS#12 format. Additionally, the certificate can be provided as
 					an inline string in PEM format.
 
-					If this is set, and is not a PKCS#12 archive, `key_file` must also be set.
+					If this is set _and_ is not a PKCS#12 archive, `key_file` must also be set.
 					"""
 				required: false
 				type: string: examples: ["/path/to/host_certificate.crt"]
@@ -493,7 +493,7 @@ base: components: sinks: amqp: configuration: {
 					If enabled, certificates must not be expired and must be issued by a trusted
 					issuer. This verification operates in a hierarchical manner, checking that the leaf certificate (the
 					certificate presented by the client/server) is not only valid, but that the issuer of that certificate is also valid, and
-					so on until the verification process reaches a root certificate.
+					so on, until the verification process reaches a root certificate.
 
 					Do NOT set this to `false` unless you understand the risks of not verifying the validity of certificates.
 					"""

website/cue/reference/components/sinks/base/appsignal.cue

@@ -14,9 +14,9 @@ base: components: sinks: appsignal: configuration: {
 			description: """
 				Whether or not end-to-end acknowledgements are enabled.
 
-				When enabled for a sink, any source connected to that sink where the source supports
-				end-to-end acknowledgements as well, waits for events to be acknowledged by **all
-				connected** sinks before acknowledging them at the source.
+				When enabled for a sink, any source that supports end-to-end
+				acknowledgements that is connected to that sink waits for events
+				to be acknowledged by **all connected sinks** before acknowledging them at the source.
 
 				Enabling or disabling acknowledgements at the sink level takes precedence over any global
 				[`acknowledgements`][global_acks] configuration.
@@ -331,7 +331,7 @@ base: components: sinks: appsignal: configuration: {
 				description: """
 					Sets the list of supported ALPN protocols.
 
-					Declare the supported ALPN protocols, which are used during negotiation with peer. They are prioritized in the order
+					Declare the supported ALPN protocols, which are used during negotiation with a peer. They are prioritized in the order
 					that they are defined.
 					"""
 				required: false
@@ -353,7 +353,7 @@ base: components: sinks: appsignal: configuration: {
 					The certificate must be in DER, PEM (X.509), or PKCS#12 format. Additionally, the certificate can be provided as
 					an inline string in PEM format.
 
-					If this is set, and is not a PKCS#12 archive, `key_file` must also be set.
+					If this is set _and_ is not a PKCS#12 archive, `key_file` must also be set.
 					"""
 				required: false
 				type: string: examples: ["/path/to/host_certificate.crt"]
@@ -404,7 +404,7 @@ base: components: sinks: appsignal: configuration: {
 					If enabled, certificates must not be expired and must be issued by a trusted
 					issuer. This verification operates in a hierarchical manner, checking that the leaf certificate (the
 					certificate presented by the client/server) is not only valid, but that the issuer of that certificate is also valid, and
-					so on until the verification process reaches a root certificate.
+					so on, until the verification process reaches a root certificate.
 
 					Do NOT set this to `false` unless you understand the risks of not verifying the validity of certificates.
 					"""