docs: Editorial edits for updated component descriptions (vectordotde…

…v#18590)

* editorial edits

* revert changes and change to double forward slashes

* small edits

* update docs

---------

Co-authored-by: Toby Lawrence <toby@nuclearfurnace.com>

lib/codecs/src/decoding/format/gelf.rs

@@ -20,11 +20,11 @@ use super::{default_lossy, Deserializer};
 use crate::gelf::GELF_TARGET_PATHS;
 use crate::{gelf_fields::*, VALID_FIELD_REGEX};
 
-/// On GELF decoding behavior:
-///   Graylog has a relaxed decoding. They are much more lenient than the spec would
-///   suggest. We've elected to take a more strict approach to maintain backwards compatibility
-///   in the event that we need to change the behavior to be more relaxed, so that prior versions
-///   of vector will still work with the new relaxed decoding.
+// On GELF decoding behavior:
+//   Graylog has a relaxed decoding. They are much more lenient than the spec would
+//   suggest. We've elected to take a more strict approach to maintain backwards compatibility
+//   in the event that we need to change the behavior to be more relaxed, so that prior versions
+//   of vector will still work with the new relaxed decoding.
 
 /// Config used to build a `GelfDeserializer`.
 #[configurable_component]

lib/codecs/src/decoding/mod.rs

@@ -216,15 +216,15 @@ pub enum DeserializerConfig {
     /// [rfc5424]: https://www.ietf.org/rfc/rfc5424.txt
     Syslog(SyslogDeserializerConfig),
 
-    /// Decodes the raw bytes as Vector’s [native Protocol Buffers format][vector_native_protobuf].
+    /// Decodes the raw bytes as [native Protocol Buffers format][vector_native_protobuf].
     ///
     /// This codec is **[experimental][experimental]**.
     ///
     /// [vector_native_protobuf]: https://github.com/vectordotdev/vector/blob/master/lib/vector-core/proto/event.proto
     /// [experimental]: https://vector.dev/highlights/2022-03-31-native-event-codecs
     Native,
 
-    /// Decodes the raw bytes as Vector’s [native JSON format][vector_native_json].
+    /// Decodes the raw bytes as [native JSON format][vector_native_json].
     ///
     /// This codec is **[experimental][experimental]**.
     ///

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

@@ -15,22 +15,22 @@ use vector_core::{
 #[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]
 #[serde(rename_all = "snake_case")]
 pub enum QuoteStyle {
-    /// This puts quotes around every field. Always.
+    /// Always puts quotes around every field.
     Always,
 
-    /// This puts quotes around fields only when necessary.
-    /// They are necessary when fields contain a quote, delimiter or record terminator.
+    /// Puts quotes around fields only when necessary.
+    /// They are necessary when fields contain a quote, delimiter, or record terminator.
     /// Quotes are also necessary when writing an empty record
     /// (which is indistinguishable from a record with one empty field).
     #[default]
     Necessary,
 
-    /// This puts quotes around all fields that are 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 will be used even if they aren’t strictly necessary.
+    /// then quotes are used even if they aren't strictly necessary.
     NonNumeric,
 
-    /// This never writes quotes, even if it would produce invalid CSV data.
+    /// Never writes quotes, even if it produces invalid CSV data.
     Never,
 }
 
@@ -97,7 +97,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 it is ignored.
     #[serde(
         default = "default_escape",
         with = "vector_core::serde::ascii_char",

src/sources/file.rs

@@ -206,15 +206,15 @@ pub struct FileConfig {
     pub multiline: Option<MultilineConfig>,
 
     /// Max amount of bytes to read from a single file before switching over to the next file.
-    /// **Note:** This does not apply when `oldest_first` is `true.
+    /// **Note:** This does not apply when `oldest_first` is `true`.
     ///
     /// This allows distributing the reads more or less evenly across
     /// the files.
     #[serde(default = "default_max_read_bytes")]
     #[configurable(metadata(docs::type_unit = "bytes"))]
     pub max_read_bytes: usize,
 
-    /// Instead of balancing read capacity fairly across all watched files, prioritize draining the oldest files before moving on to read data from younger files.
+    /// Instead of balancing read capacity fairly across all watched files, prioritize draining the oldest files before moving on to read data from more recent files.
     #[serde(default)]
     pub oldest_first: bool,
 

src/sources/kubernetes_logs/mod.rs

@@ -164,14 +164,14 @@ pub struct Config {
     ignore_older_secs: Option<u64>,
 
     /// Max amount of bytes to read from a single file before switching over to the next file.
-    /// **Note:** This does not apply when `oldest_first` is `true.
+    /// **Note:** This does not apply when `oldest_first` is `true`.
     ///
     /// This allows distributing the reads more or less evenly across
     /// the files.
     #[configurable(metadata(docs::type_unit = "bytes"))]
     max_read_bytes: usize,
 
-    /// Instead of balancing read capacity fairly across all watched files, prioritize draining the oldest files before moving on to read data from younger files.
+    /// Instead of balancing read capacity fairly across all watched files, prioritize draining the oldest files before moving on to read data from more recent files.
     #[serde(default = "default_oldest_first")]
     pub oldest_first: bool,
 

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

@@ -158,7 +158,7 @@ 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 it is ignored.
 																"""
 						required: false
 						type: uint: default: 34
@@ -187,18 +187,18 @@ base: components: sinks: amqp: configuration: {
 						type: string: {
 							default: "necessary"
 							enum: {
-								always: "This puts quotes around every field. Always."
+								always: "Always puts quotes around every field."
 								necessary: """
-																			This puts quotes around fields only when necessary.
-																			They are necessary when fields contain a quote, delimiter or record terminator.
+																			Puts quotes around fields only when necessary.
+																			They are necessary when fields contain a quote, delimiter, or record terminator.
 																			Quotes are also necessary when writing an empty record
 																			(which is indistinguishable from a record with one empty field).
 																			"""
-								never: "This never writes quotes, even if it would produce invalid CSV data."
+								never: "Never writes quotes, even if it produces invalid CSV data."
 								non_numeric: """
-																			This puts quotes around all fields that are 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 will be used even if they aren’t strictly necessary.
+																			then quotes are used even if they aren't strictly necessary.
 																			"""
 							}
 						}

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

@@ -329,7 +329,7 @@ base: components: sinks: aws_cloudwatch_logs: 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 it is ignored.
 																"""
 						required: false
 						type: uint: default: 34
@@ -358,18 +358,18 @@ base: components: sinks: aws_cloudwatch_logs: configuration: {
 						type: string: {
 							default: "necessary"
 							enum: {
-								always: "This puts quotes around every field. Always."
+								always: "Always puts quotes around every field."
 								necessary: """
-																			This puts quotes around fields only when necessary.
-																			They are necessary when fields contain a quote, delimiter or record terminator.
+																			Puts quotes around fields only when necessary.
+																			They are necessary when fields contain a quote, delimiter, or record terminator.
 																			Quotes are also necessary when writing an empty record
 																			(which is indistinguishable from a record with one empty field).
 																			"""
-								never: "This never writes quotes, even if it would produce invalid CSV data."
+								never: "Never writes quotes, even if it produces invalid CSV data."
 								non_numeric: """
-																			This puts quotes around all fields that are 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 will be used even if they aren’t strictly necessary.
+																			then quotes are used even if they aren't strictly necessary.
 																			"""
 							}
 						}

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

@@ -308,7 +308,7 @@ base: components: sinks: aws_kinesis_firehose: 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 it is ignored.
 																"""
 						required: false
 						type: uint: default: 34
@@ -337,18 +337,18 @@ base: components: sinks: aws_kinesis_firehose: configuration: {
 						type: string: {
 							default: "necessary"
 							enum: {
-								always: "This puts quotes around every field. Always."
+								always: "Always puts quotes around every field."
 								necessary: """
-																			This puts quotes around fields only when necessary.
-																			They are necessary when fields contain a quote, delimiter or record terminator.
+																			Puts quotes around fields only when necessary.
+																			They are necessary when fields contain a quote, delimiter, or record terminator.
 																			Quotes are also necessary when writing an empty record
 																			(which is indistinguishable from a record with one empty field).
 																			"""
-								never: "This never writes quotes, even if it would produce invalid CSV data."
+								never: "Never writes quotes, even if it produces invalid CSV data."
 								non_numeric: """
-																			This puts quotes around all fields that are 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 will be used even if they aren’t strictly necessary.
+																			then quotes are used even if they aren't strictly necessary.
 																			"""
 							}
 						}

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

@@ -308,7 +308,7 @@ base: components: sinks: aws_kinesis_streams: 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 it is ignored.
 																"""
 						required: false
 						type: uint: default: 34
@@ -337,18 +337,18 @@ base: components: sinks: aws_kinesis_streams: configuration: {
 						type: string: {
 							default: "necessary"
 							enum: {
-								always: "This puts quotes around every field. Always."
+								always: "Always puts quotes around every field."
 								necessary: """
-																			This puts quotes around fields only when necessary.
-																			They are necessary when fields contain a quote, delimiter or record terminator.
+																			Puts quotes around fields only when necessary.
+																			They are necessary when fields contain a quote, delimiter, or record terminator.
 																			Quotes are also necessary when writing an empty record
 																			(which is indistinguishable from a record with one empty field).
 																			"""
-								never: "This never writes quotes, even if it would produce invalid CSV data."
+								never: "Never writes quotes, even if it produces invalid CSV data."
 								non_numeric: """
-																			This puts quotes around all fields that are 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 will be used even if they aren’t strictly necessary.
+																			then quotes are used even if they aren't strictly necessary.
 																			"""
 							}
 						}

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

@@ -417,7 +417,7 @@ base: components: sinks: aws_s3: 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 it is ignored.
 																"""
 						required: false
 						type: uint: default: 34
@@ -446,18 +446,18 @@ base: components: sinks: aws_s3: configuration: {
 						type: string: {
 							default: "necessary"
 							enum: {
-								always: "This puts quotes around every field. Always."
+								always: "Always puts quotes around every field."
 								necessary: """
-																			This puts quotes around fields only when necessary.
-																			They are necessary when fields contain a quote, delimiter or record terminator.
+																			Puts quotes around fields only when necessary.
+																			They are necessary when fields contain a quote, delimiter, or record terminator.
 																			Quotes are also necessary when writing an empty record
 																			(which is indistinguishable from a record with one empty field).
 																			"""
-								never: "This never writes quotes, even if it would produce invalid CSV data."
+								never: "Never writes quotes, even if it produces invalid CSV data."
 								non_numeric: """
-																			This puts quotes around all fields that are 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 will be used even if they aren’t strictly necessary.
+																			then quotes are used even if they aren't strictly necessary.
 																			"""
 							}
 						}

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

@@ -244,7 +244,7 @@ base: components: sinks: aws_sns: 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 it is ignored.
 																"""
 						required: false
 						type: uint: default: 34
@@ -273,18 +273,18 @@ base: components: sinks: aws_sns: configuration: {
 						type: string: {
 							default: "necessary"
 							enum: {
-								always: "This puts quotes around every field. Always."
+								always: "Always puts quotes around every field."
 								necessary: """
-																			This puts quotes around fields only when necessary.
-																			They are necessary when fields contain a quote, delimiter or record terminator.
+																			Puts quotes around fields only when necessary.
+																			They are necessary when fields contain a quote, delimiter, or record terminator.
 																			Quotes are also necessary when writing an empty record
 																			(which is indistinguishable from a record with one empty field).
 																			"""
-								never: "This never writes quotes, even if it would produce invalid CSV data."
+								never: "Never writes quotes, even if it produces invalid CSV data."
 								non_numeric: """
-																			This puts quotes around all fields that are 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 will be used even if they aren’t strictly necessary.
+																			then quotes are used even if they aren't strictly necessary.
 																			"""
 							}
 						}

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

@@ -244,7 +244,7 @@ base: components: sinks: aws_sqs: 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 it is ignored.
 																"""
 						required: false
 						type: uint: default: 34
@@ -273,18 +273,18 @@ base: components: sinks: aws_sqs: configuration: {
 						type: string: {
 							default: "necessary"
 							enum: {
-								always: "This puts quotes around every field. Always."
+								always: "Always puts quotes around every field."
 								necessary: """
-																			This puts quotes around fields only when necessary.
-																			They are necessary when fields contain a quote, delimiter or record terminator.
+																			Puts quotes around fields only when necessary.
+																			They are necessary when fields contain a quote, delimiter, or record terminator.
 																			Quotes are also necessary when writing an empty record
 																			(which is indistinguishable from a record with one empty field).
 																			"""
-								never: "This never writes quotes, even if it would produce invalid CSV data."
+								never: "Never writes quotes, even if it produces invalid CSV data."
 								non_numeric: """
-																			This puts quotes around all fields that are 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 will be used even if they aren’t strictly necessary.
+																			then quotes are used even if they aren't strictly necessary.
 																			"""
 							}
 						}