Document all condition fields

lib/cache/memory.go

@@ -30,7 +30,6 @@ The field ` + "`init_values`" + ` can be used to prepopulate the memory cache
 with any number of key/value pairs which are exempt from TTLs:
 
 ` + "```yaml" + `
-type: memory
 memory:
   ttl: 60
   init_values:

lib/condition/all.go

@@ -14,11 +14,11 @@ import (
 func init() {
 	Constructors[TypeAll] = TypeSpec{
 		constructor: NewAll,
-		Description: `
-All is a condition that tests a child condition against each message of a batch
+		Summary: `
+A condition that tests a child condition against each message of a batch
 individually. If all messages pass the child condition then this condition also
-passes.
-
+passes.`,
+		Description: `
 For example, if we wanted to check that all messages of a batch contain the word
 'foo' we could use this config:
 

lib/condition/and.go

@@ -13,11 +13,13 @@ import (
 func init() {
 	Constructors[TypeAnd] = TypeSpec{
 		constructor: NewAnd,
+		Summary: `
+And is a condition that returns the logical AND of its children conditions.`,
 		Description: `
-And is a condition that returns the logical AND of its children conditions:
+For example, the following resolves true if a message contains both 'foo' and
+'bar':
 
-` + "``` yaml" + `
-# True if message contains both 'foo' and 'bar'
+` + "```yaml" + `
 and:
   - text:
       operator: contains

lib/condition/any.go

@@ -14,11 +14,11 @@ import (
 func init() {
 	Constructors[TypeAny] = TypeSpec{
 		constructor: NewAny,
-		Description: `
-Any is a condition that tests a child condition against each message of a batch
+		Summary: `
+A condition that tests a child condition against each message of a batch
 individually. If any message passes the child condition then this condition also
-passes.
-
+passes.`,
+		Description: `
 For example, if we wanted to check that at least one message of a batch contains
 the word 'foo' we could use this config:
 

lib/condition/bounds_check.go

@@ -6,15 +6,23 @@ import (
 	"github.com/Jeffail/benthos/v3/lib/log"
 	"github.com/Jeffail/benthos/v3/lib/metrics"
 	"github.com/Jeffail/benthos/v3/lib/types"
+	"github.com/Jeffail/benthos/v3/lib/x/docs"
 )
 
 //------------------------------------------------------------------------------
 
 func init() {
 	Constructors[TypeBoundsCheck] = TypeSpec{
 		constructor: NewBoundsCheck,
-		Description: `
-Checks a message against a set of bounds.`,
+		Summary: `
+Checks a message against a set of bounds, if any bound fails then this condition
+resolves to false.`,
+		FieldSpecs: docs.FieldSpecs{
+			docs.FieldCommon("max_part_size", "The maximum size of a message to allow (in bytes)"),
+			docs.FieldCommon("min_part_size", "The minimum size of a message to allow (in bytes)"),
+			docs.FieldAdvanced("max_parts", "The maximum size of message batches to allow (in message count)"),
+			docs.FieldAdvanced("min_parts", "The minimum size of message batches to allow (in message count)"),
+		},
 	}
 }
 

lib/condition/check_field.go

@@ -8,6 +8,7 @@ import (
 	"github.com/Jeffail/benthos/v3/lib/log"
 	"github.com/Jeffail/benthos/v3/lib/metrics"
 	"github.com/Jeffail/benthos/v3/lib/types"
+	"github.com/Jeffail/benthos/v3/lib/x/docs"
 	"github.com/Jeffail/gabs/v2"
 )
 
@@ -16,7 +17,7 @@ import (
 func init() {
 	Constructors[TypeCheckField] = TypeSpec{
 		constructor: NewCheckField,
-		Description: `
+		Summary: `
 Extracts the value of a field identified via [dot path](/docs/configuration/field_paths)
 within messages (currently only JSON format is supported) and then tests the
 extracted value against a child condition.`,
@@ -34,6 +35,19 @@ extracted value against a child condition.`,
 				"condition": condConf,
 			}, nil
 		},
+		FieldSpecs: docs.FieldSpecs{
+			docs.FieldCommon("path", "A [field path](/docs/configuration/field_paths) to check against the child condition."),
+			docs.FieldCommon("condition", "A child condition to test the field contents against."),
+			docs.FieldAdvanced(
+				"parts",
+				`An optional array of message indexes of a batch that the condition should apply to.
+If left empty all messages are processed. This field is only applicable when
+batching messages [at the input level](/docs/configuration/batching).
+
+Indexes can be negative, and if so the part will be selected from the end
+counting backwards starting from -1.`,
+			),
+		},
 	}
 }
 

lib/condition/check_interpolation.go

@@ -9,18 +9,19 @@ import (
 	"github.com/Jeffail/benthos/v3/lib/metrics"
 	"github.com/Jeffail/benthos/v3/lib/types"
 	"github.com/Jeffail/benthos/v3/lib/util/text"
+	"github.com/Jeffail/benthos/v3/lib/x/docs"
 )
 
 //------------------------------------------------------------------------------
 
 func init() {
 	Constructors[TypeCheckInterpolation] = TypeSpec{
 		constructor: NewCheckInterpolation,
-		Description: `
+		Summary: `
 Resolves a string containing
 [function interpolations](/docs/configuration/interpolation#functions) and then tests
-the result against a child condition.
-
+the result against a child condition.`,
+		Description: `
 For example, you could use this to test against the size of a message batch:
 
 ` + "``` yaml" + `
@@ -44,6 +45,15 @@ check_interpolation:
 				"condition": condConf,
 			}, nil
 		},
+		FieldSpecs: docs.FieldSpecs{
+			docs.FieldCommon(
+				"value", "The value to check against the child condition.",
+				"${!json_field:doc.title}",
+				"${!metadata:kafka_topic}",
+				"${!json_field:doc.id}-${!metadata:kafka_key}",
+			).SupportsInterpolation(true),
+			docs.FieldCommon("condition", "A child condition to test the field contents against."),
+		},
 	}
 }
 

lib/condition/count.go

@@ -6,24 +6,47 @@ import (
 	"github.com/Jeffail/benthos/v3/lib/log"
 	"github.com/Jeffail/benthos/v3/lib/metrics"
 	"github.com/Jeffail/benthos/v3/lib/types"
+	"github.com/Jeffail/benthos/v3/lib/x/docs"
 )
 
 //------------------------------------------------------------------------------
 
 func init() {
 	Constructors[TypeCount] = TypeSpec{
 		constructor: NewCount,
-		Description: `
+		Summary: `
 Counts messages starting from one, returning true until the counter reaches its
-target, at which point it will return false and reset the counter. This
-condition is useful when paired with the ` + "`read_until`" + ` input, as it can
-be used to cut the input stream off once a certain number of messages have been
-read.
-
-It is worth noting that each discrete count condition will have its own counter.
-Parallel processors containing a count condition will therefore count
-independently. It is, however, possible to share the counter across processor
-pipelines by defining the count condition as a resource.`,
+target, at which point it will return false and reset the counter.`,
+		Description: `
+Each discrete count condition will have its own counter. Parallel processors
+containing a count condition will therefore count independently. It is, however,
+possible to share the counter across processor pipelines by defining the count
+condition as a resource.`,
+		FieldSpecs: docs.FieldSpecs{
+			docs.FieldCommon("arg", "A number to count towards."),
+		},
+		Footnotes: `
+## Examples
+
+This condition is useful when paired with the
+` + "[`read_until`](/docs/components/inputs/read_until)" + ` input, as it can be
+used to cut the input stream off once a certain number of messages have been
+read:
+
+` + "```yaml" + `
+# Only read 100 messages, and then exit.
+input:
+  read_until:
+    input:
+      kafka_balanced:
+        addresses: [ TODO ]
+        topics: [ foo, bar ]
+        consumer_group: foogroup
+      condition:
+        not:
+          count:
+            arg: 100
+` + "```" + ``,
 	}
 }
 

lib/condition/docs.go

@@ -0,0 +1,13 @@
+package condition
+
+import "github.com/Jeffail/benthos/v3/lib/x/docs"
+
+var partFieldSpec = docs.FieldAdvanced(
+	"part",
+	`The index of a message within a batch to test the condition against. This
+field is only applicable when batching messages
+[at the input level](/docs/configuration/batching).
+
+Indexes can be negative, and if so the part will be selected from the end
+counting backwards starting from -1.`,
+)

lib/condition/jmespath.go

@@ -6,6 +6,7 @@ import (
 	"github.com/Jeffail/benthos/v3/lib/log"
 	"github.com/Jeffail/benthos/v3/lib/metrics"
 	"github.com/Jeffail/benthos/v3/lib/types"
+	"github.com/Jeffail/benthos/v3/lib/x/docs"
 	jmespath "github.com/jmespath/go-jmespath"
 )
 
@@ -14,18 +15,27 @@ import (
 func init() {
 	Constructors[TypeJMESPath] = TypeSpec{
 		constructor: NewJMESPath,
+		Summary: `
+Parses a message as a JSON blob and attempts to apply a JMESPath expression to
+it, expecting a boolean result. If the response is true the condition passes,
+otherwise it does not.`,
 		Description: `
-Parses a message part as a JSON blob and attempts to apply a JMESPath expression
-to it, expecting a boolean response. If the response is true the condition
-passes, otherwise it does not. Please refer to the
-[JMESPath website](http://jmespath.org/) for information and tutorials regarding
-the syntax of expressions.
-
-For example, with the following config:
+Please refer to the [JMESPath website](http://jmespath.org/) for information and
+tutorials regarding the syntax of expressions.`,
+		FieldSpecs: docs.FieldSpecs{
+			docs.FieldCommon(
+				"query", "A [JMESPath](http://jmespath.org/) query.",
+				"foo == 'bar'", "length(doc.urls) > `0`",
+			),
+			partFieldSpec,
+		},
+		Footnotes: `
+## Examples
+
+With the following config:
 
 ` + "``` yaml" + `
 jmespath:
-  part: 0
   query: a == 'foo'
 ` + "```" + `
 

lib/condition/jsonschema.go

@@ -7,6 +7,7 @@ import (
 	"github.com/Jeffail/benthos/v3/lib/log"
 	"github.com/Jeffail/benthos/v3/lib/metrics"
 	"github.com/Jeffail/benthos/v3/lib/types"
+	"github.com/Jeffail/benthos/v3/lib/x/docs"
 	jsonschema "github.com/xeipuuv/gojsonschema"
 )
 
@@ -15,14 +16,17 @@ import (
 func init() {
 	Constructors[TypeJSONSchema] = TypeSpec{
 		constructor: NewJSONSchema,
-		Description: `
+		Summary: `
 Validates a message against the provided JSONSchema definition to retrieve a
-boolean response indicating whether the message matches the schema or not.
+boolean response indicating whether the message matches the schema or not.`,
+		Description: `
 If the response is true the condition passes, otherwise it does not. Please
 refer to the [JSON Schema website](https://json-schema.org/) for information and
-tutorials regarding the syntax of the schema.
+tutorials regarding the syntax of the schema.`,
+		Footnotes: `
+## Examples
 
-For example, with the following JSONSchema document:
+With the following JSONSchema document:
 
 ` + "``` json" + `
 {
@@ -52,7 +56,6 @@ And the following Benthos configuration:
 
 ` + "``` yaml" + `
 json_schema:
-  part: 0
   schema_path: "file://path_to_schema.json"
 ` + "```" + `
 
@@ -63,6 +66,11 @@ If the message being processed looked like:
 ` + "```" + `
 
 Then the condition would pass.`,
+		FieldSpecs: docs.FieldSpecs{
+			docs.FieldCommon("schema", "A schema to apply. Use either this or the `schema_path` field."),
+			docs.FieldCommon("schema_path", "The path of a schema document to apply. Use either this or the `schema` field."),
+			partFieldSpec,
+		},
 	}
 }