chore(external docs): First batch of editorial edits for the Functions doc (vectordotdev#18780)

* make edits

* more edits

* apply suggestions

* Apply suggestions from code review

Co-authored-by: cecilia saixue watt <[email protected]>

* cue fmt

Signed-off-by: Jesse Szwedko <[email protected]>

---------

Signed-off-by: Jesse Szwedko <[email protected]>
Co-authored-by: cecilia saixue watt <[email protected]>
Co-authored-by: Jesse Szwedko <[email protected]>

Author: 3 people

website/cue/reference/remap/functions.cue

@@ -59,10 +59,10 @@ remap: {
 
 	// Reusable text
 	_enrichment_table_explainer: """
-		For `file` enrichment tables this condition needs to be a VRL object in which
+		For `file` enrichment tables, this condition needs to be a VRL object in which
 		the key-value pairs indicate a field to	search mapped to a value to search in that field.
 		This function returns the rows that match the provided condition(s). _All_ fields need to
-		match for rows to be returned; if any fields don't match, no rows are returned.
+		match for rows to be returned; if any fields do not match, then no rows are returned.
 
 		There are currently two forms of search criteria:
 
@@ -72,15 +72,15 @@ remap: {
 		   performance perspective.
 
 		2. **Date range search**. The given field must be greater than or equal to the `from` date
-		   and less than or equal to the `to` date. Note that a date range search involves
-		   sequentially scanning through the rows that have been located via any exact match
+		   and less than or equal to the `to` date. A date range search involves
+		   sequentially scanning through the rows that have been located using any exact match
 		   criteria. This can be an expensive operation if there are many rows returned by any exact
-		   match criteria. We recommend using date ranges as the _only_ criteria when the enrichment
+		   match criteria. Therefore, use date ranges as the _only_ criteria when the enrichment
 		   data set is very small.
 
-		For `geoip` enrichment tables this condition needs to be a VRL object with a single key-value pair
+		For `geoip` enrichment tables, this condition needs to be a VRL object with a single key-value pair
 		whose value needs to be a valid IP address. Example: `{"ip": .ip }`. If a return field is expected
-		and without a value, `null` will be used. This table can return following fields:
+		and without a value, `null` is used. This table can return the following fields:
 
 		* ISP databases:
 			* `autonomous_system_number`

website/cue/reference/remap/functions/append.cue

@@ -9,13 +9,13 @@ remap: functions: append: {
 	arguments: [
 		{
 			name:        "value"
-			description: "The initial array"
+			description: "The initial array."
 			required:    true
 			type: ["array"]
 		},
 		{
 			name:        "items"
-			description: "The items to append"
+			description: "The items to append."
 			required:    true
 			type: ["array"]
 		},

website/cue/reference/remap/functions/assert.cue

@@ -26,14 +26,14 @@ remap: functions: assert: {
 			description: """
 				An optional custom error message. If the equality assertion fails, `message` is
 				appended to the default message prefix. See the [examples](#assert-examples) below
-				for a sample fully formed log message.
+				for a fully formed log message sample.
 				"""
 			required: false
 			type: ["string"]
 		},
 	]
 	internal_failure_reasons: [
-		"`condition` evaluates to `false`",
+		"`condition` evaluates to `false`.",
 	]
 	return: types: ["null"]
 

website/cue/reference/remap/functions/assert_eq.cue

@@ -5,7 +5,7 @@ remap: functions: assert_eq: {
 
 	description: """
 		Asserts that two expressions, `left` and `right`, have the same value. The program is
-		aborted with the `message` if they are unequal.
+		aborted with `message` if they do not have the same value.
 		"""
 
 	notices: [
@@ -34,7 +34,7 @@ remap: functions: assert_eq: {
 			description: """
 				An optional custom error message. If the equality assertion fails, `message` is
 				appended to the default message prefix. See the [examples](#assert_eq-examples)
-				below for a sample fully formed log message.
+				below for a fully formed log message sample.
 				"""
 			required: false
 			type: ["string"]

website/cue/reference/remap/functions/chunks.cue

@@ -3,7 +3,7 @@ package metadata
 remap: functions: chunks: {
 	category: "Array"
 	description: """
-		Chunks `value` into slices of length `chunk_size` bytes
+		Chunks `value` into slices of length `chunk_size` bytes.
 		"""
 
 	arguments: [
@@ -21,8 +21,8 @@ remap: functions: chunks: {
 		},
 	]
 	internal_failure_reasons: [
-		"`chunk_size` must be at least 1 byte",
-		"`chunk_size` is too large",
+		"`chunk_size` must be at least 1 byte.",
+		"`chunk_size` is too large.",
 	]
 	return: {
 		types: ["array"]

website/cue/reference/remap/functions/compact.cue

@@ -3,7 +3,7 @@ package metadata
 remap: functions: compact: {
 	category: "Enumerate"
 	description: """
-		Compacts the `value` by removing "empty" values, where emptiness is defined using the
+		Compacts the `value` by removing empty values, where empty values are defined using the
 		available parameters.
 		"""
 

website/cue/reference/remap/functions/decrypt.cue

@@ -33,7 +33,7 @@ remap: functions: decrypt: {
 	arguments: [
 		{
 			name:        "ciphertext"
-			description: "The string to decrypt. The should be raw bytes (not encoded)."
+			description: "The string in raw bytes (not encoded) to decrypt."
 			required:    true
 			type: ["string"]
 		},
@@ -45,14 +45,14 @@ remap: functions: decrypt: {
 		},
 		{
 			name:        "key"
-			description: "The key for decryption. The should be raw bytes of the key (not encoded). The length must match the algorithm requested."
+			description: "The key in raw bytes (not encoded) for decryption. The length must match the algorithm requested."
 			required:    true
 			type: ["string"]
 		},
 		{
 			name: "iv"
 			description: #"""
-				The IV for decryption. The should be raw bytes of the IV (not encoded). The length must match the algorithm requested.
+				The IV in raw bytes (not encoded) for decryption. The length must match the algorithm requested.
 				A new IV should be generated for every message. You can use `random_bytes` to generate a cryptographically secure random value.
 				The value should match the one used during encryption.
 				"""#
@@ -61,9 +61,9 @@ remap: functions: decrypt: {
 		},
 	]
 	internal_failure_reasons: [
-		"`algorithm` isn't a supported algorithm",
-		"`key` length doesn't match the key size required for the algorithm specified",
-		"`iv` length doesn't match the iv size required for the algorithm specified",
+		"`algorithm` is not a supported algorithm.",
+		"`key` length does not match the key size required for the algorithm specified.",
+		"`iv` length does not match the `iv` size required for the algorithm specified.",
 	]
 	return: types: ["string"]
 

website/cue/reference/remap/functions/encode_key_value.cue

@@ -3,7 +3,7 @@ package metadata
 remap: functions: encode_key_value: {
 	category:    "Codec"
 	description: """
-		Encodes the `value` to in key/value format with customizable delimiters. Default delimiters match
+		Encodes the `value` into key-value format with customizable delimiters. Default delimiters match
 		the [logfmt](\(urls.logfmt)) format.
 		"""
 	notices: [
@@ -21,7 +21,7 @@ remap: functions: encode_key_value: {
 		},
 		{
 			name:        "fields_ordering"
-			description: "The ordering of fields to preserve. Any fields not in this list will appear unordered, after any ordered fields."
+			description: "The ordering of fields to preserve. Any fields not in this list are listed unordered, after all ordered fields."
 			required:    false
 			type: ["array"]
 		},
@@ -34,21 +34,21 @@ remap: functions: encode_key_value: {
 		},
 		{
 			name:        "field_delimiter"
-			description: "The string that separates each key/value pair."
+			description: "The string that separates each key-value pair."
 			required:    false
 			default:     " "
 			type: ["string"]
 		},
 		{
 			name:        "flatten_boolean"
-			description: "Whether to encode key/value with a boolean value as a standalone key if `true` and nothing if `false`."
+			description: "Whether to encode key-value with a boolean value as a standalone key if `true` and nothing if `false`."
 			required:    false
 			type: ["boolean"]
 			default: false
 		},
 	]
 	internal_failure_reasons: [
-		"`fields_ordering` contains a non-string element",
+		"`fields_ordering` contains a non-string element.",
 	]
 	return: types: ["string"]
 

website/cue/reference/remap/functions/encode_logfmt.cue

@@ -16,13 +16,13 @@ remap: functions: encode_logfmt: {
 		},
 		{
 			name:        "fields_ordering"
-			description: "The ordering of fields to preserve. Any fields not in this list will appear unordered, after any ordered fields."
+			description: "The ordering of fields to preserve. Any fields not in this list are listed unordered, after all ordered fields."
 			required:    false
 			type: ["array"]
 		},
 	]
 	internal_failure_reasons: [
-		"`fields_ordering` contains a non-string element",
+		"`fields_ordering` contains a non-string element.",
 	]
 	return: types: ["string"]
 

website/cue/reference/remap/functions/encode_percent.cue

@@ -15,7 +15,7 @@ remap: functions: encode_percent: {
 		},
 		{
 			name:        "ascii_set"
-			description: "The ascii set to use when encoding the data."
+			description: "The ASCII set to use when encoding the data."
 			required:    false
 			type: ["string"]
 			default: "NON_ALPHANUMERIC"