chore(external docs): First batch of editorial edits for the Function…

…s 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]>
aholmberg · Oct 17, 2023 · 1da9005 · 1da9005
1 parent 0568d7a
commit 1da9005
Show file tree

Hide file tree

Showing 75 changed files with 171 additions and 179 deletions.
diff --git a/website/cue/reference/remap/functions.cue b/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`

diff --git a/website/cue/reference/remap/functions/append.cue b/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"]
 		},

diff --git a/website/cue/reference/remap/functions/assert.cue b/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"]
 

diff --git a/website/cue/reference/remap/functions/assert_eq.cue b/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"]

diff --git a/website/cue/reference/remap/functions/chunks.cue b/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"]

diff --git a/website/cue/reference/remap/functions/compact.cue b/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.
 		"""
 

diff --git a/website/cue/reference/remap/functions/decrypt.cue b/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"]
 

diff --git a/website/cue/reference/remap/functions/encode_key_value.cue b/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"]
 

diff --git a/website/cue/reference/remap/functions/encode_logfmt.cue b/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"]
 

diff --git a/website/cue/reference/remap/functions/encode_percent.cue b/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"

diff --git a/website/cue/reference/remap/functions/encrypt.cue b/website/cue/reference/remap/functions/encrypt.cue
@@ -54,24 +54,24 @@ remap: functions: encrypt: {
 		},
 		{
 			name:        "key"
-			description: "The key for encryption. 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 encryption. The length must match the algorithm requested."
 			required:    true
 			type: ["string"]
 		},
 		{
 			name: "iv"
 			description: #"""
-				The IV for encryption. 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 encryption. 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.
 				"""#
 			required: true
 			type: ["string"]
 		},
 	]
 	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"]
 

diff --git a/website/cue/reference/remap/functions/filter.cue b/website/cue/reference/remap/functions/filter.cue
@@ -1,25 +1,23 @@
 package metadata
 
 remap: functions: filter: {
-	category:    "Enumerate"
+	category: "Enumerate"
 	description: """
 		Filter elements from a collection.
 
 		This function currently *does not* support recursive iteration.
-		If you have a need for recursive iteration using `filter`, then
-		[please let us know](\(urls.new_feature_request))!
 
-		The function uses the "function closure syntax" to allow reading
-		the key/value or index/value combination for each item in the
+		The function uses the function closure syntax to allow reading
+		the key-value or index-value combination for each item in the
 		collection.
 
 		The same scoping rules apply to closure blocks as they do for
-		regular blocks, meaning, any variable defined in parent scopes
-		are accessible, and mutations to those variables are preserved,
+		regular blocks. This means that any variable defined in parent scopes
+		is accessible, and mutations to those variables are preserved,
 		but any new variables instantiated in the closure block are
 		unavailable outside of the block.
 
-		Check out the examples below to learn about the closure syntax.
+		See the examples below to learn about the closure syntax.
 		"""
 
 	arguments: [

diff --git a/website/cue/reference/remap/functions/for_each.cue b/website/cue/reference/remap/functions/for_each.cue
@@ -1,27 +1,23 @@
 package metadata
 
 remap: functions: for_each: {
-	category:    "Enumerate"
+	category: "Enumerate"
 	description: """
 		Iterate over a collection.
 
 		This function currently *does not* support recursive iteration.
-		If you have a need for recursive iteration using `for_each`,
-		which can't be solved using the `map_keys` or `map_values`
-		enumeration functions (which *do* support recursion), then
-		[please let us know](\(urls.new_feature_request))!
 
 		The function uses the "function closure syntax" to allow reading
 		the key/value or index/value combination for each item in the
 		collection.
 
 		The same scoping rules apply to closure blocks as they do for
-		regular blocks, meaning, any variable defined in parent scopes
-		are accessible, and mutations to those variables are preserved,
+		regular blocks. This means that any variable defined in parent scopes
+		is accessible, and mutations to those variables are preserved,
 		but any new variables instantiated in the closure block are
 		unavailable outside of the block.
 
-		Check out the examples below to learn about the closure syntax.
+		See the examples below to learn about the closure syntax.
 		"""
 
 	arguments: [

diff --git a/website/cue/reference/remap/functions/format_int.cue b/website/cue/reference/remap/functions/format_int.cue
@@ -22,7 +22,7 @@ remap: functions: format_int: {
 		},
 	]
 	internal_failure_reasons: [
-		"base is not between 2 and 36",
+		"The base is not between 2 and 36.",
 	]
 	return: types: ["string"]
 

diff --git a/website/cue/reference/remap/functions/from_unix_timestamp.cue b/website/cue/reference/remap/functions/from_unix_timestamp.cue
@@ -5,8 +5,7 @@ remap: functions: from_unix_timestamp: {
 	description: """
 		Converts the `value` integer from a [Unix timestamp](\(urls.unix_timestamp)) to a VRL `timestamp`.
 
-		Converts from the number of seconds since the Unix epoch by default, but milliseconds or nanoseconds can also be
-		specified by `unit`.
+		Converts from the number of seconds since the Unix epoch by default. To convert from milliseconds or nanoseconds, set the `unit` argument to `milliseconds` or `nanoseconds`.
 		"""
 
 	arguments: [

diff --git a/website/cue/reference/remap/functions/get_enrichment_table_record.cue b/website/cue/reference/remap/functions/get_enrichment_table_record.cue
@@ -4,7 +4,7 @@ remap: functions: get_enrichment_table_record: {
 	category:    "Enrichment"
 	description: """
 		Searches an [enrichment table](\(urls.enrichment_tables_concept)) for a row that matches the
-		provided condition. A single row must be matched. If either no rows or more than one row is
+		provided condition. A single row must be matched. If no rows are found or more than one row is
 		found, an error is returned.
 
 		\(remap._enrichment_table_explainer)
@@ -37,15 +37,15 @@ remap: functions: get_enrichment_table_record: {
 		},
 		{
 			name:        "case_sensitive"
-			description: "Should text fields match case exactly."
+			description: "Whether the text fields match the case exactly."
 			required:    false
 			type: ["boolean"]
 			default: true
 		},
 	]
 	internal_failure_reasons: [
-		"The row isn't found",
-		"Multiple rows are found that match the condition",
+		"The row is not found.",
+		"Multiple rows are found that match the condition.",
 	]
 	return: types: ["object"]
 

diff --git a/website/cue/reference/remap/functions/get_secret.cue b/website/cue/reference/remap/functions/get_secret.cue
@@ -22,7 +22,7 @@ remap: functions: get_secret: {
 
 	examples: [
 		{
-			title: "Get the Datadog API key from the event metadata."
+			title: "Get the Datadog API key from the event metadata"
 			source: #"""
 				get_secret("datadog_api_key")
 				"""#

diff --git a/website/cue/reference/remap/functions/hmac.cue b/website/cue/reference/remap/functions/hmac.cue
@@ -10,8 +10,8 @@ remap: functions: hmac: {
 		string using either [encode_base16](\(urls.vrl_functions)/#encode_base16) or
 		[encode_base64](\(urls.vrl_functions)/#encode_base64).
 
-		This function is infallible if either the default `algorithm` value, or a recognized-valid compile-time
-		`algorithm` string literal is used. Otherwise it is fallible.
+		This function is infallible if either the default `algorithm` value or a recognized-valid compile-time
+		`algorithm` string literal is used. Otherwise, it is fallible.
 		"""
 
 	arguments: [

diff --git a/website/cue/reference/remap/functions/ip_aton.cue b/website/cue/reference/remap/functions/ip_aton.cue
@@ -18,7 +18,7 @@ remap: functions: ip_aton: {
 		},
 	]
 	internal_failure_reasons: [
-		"`value` isn't a valid IPv4 address",
+		"`value` is not a valid IPv4 address.",
 	]
 	return: types: ["integer"]