docs: Clarify behaviour of multiple matchers of the same type (#102)

* docs: Clarify behaviour of multiple matchers of the same type

* Apply suggestions from code review

Co-authored-by: Matt Holt <mholt@users.noreply.github.com>

* docs: Change matcher boolean wording

* Apply suggestions from code review

Co-authored-by: Matt Holt <mholt@users.noreply.github.com>

Co-authored-by: Matt Holt <mholt@users.noreply.github.com>

src/docs/markdown/caddyfile/matchers.md

@@ -139,7 +139,7 @@ Like directives, named matcher definitions must go inside the site blocks that u
 
 A named matcher definition constitutes a _matcher set_. Matchers in a set are AND'ed together; i.e. all must match. For example, if you have both a `header` and `path` matcher in the set, both must match.
 
-For most matchers that accept multiple values, those values are OR'ed; i.e. one must match in order for the matcher to match.
+Multiple matchers of the same type may be combined (e.g. multiple `path` matchers in the same set) using boolean algebra (AND/OR), as described in their respective sections below.
 
 
 
@@ -249,14 +249,24 @@ By request header fields.
 	- If enclosed by `*`, it performs a fast substring match.
 	- Otherwise, it is a fast exact match.
 
+Different header fields within the same set are AND-ed. Multiple values per field are OR'ed.
+
 #### Example:
 
-Match requests with the Connection header containing `Upgrade`.
+Match requests with the `Connection` header containing `Upgrade`.
 
 ```caddy-d
 header Connection *Upgrade*
 ```
 
+Match requests with the `Foo` header containing `bar` OR `baz`.
+```caddy-d
+@foo {
+	header Foo bar
+	header Foo baz
+}
+```
+
 
 ---
 ### header_regexp
@@ -267,6 +277,8 @@ header_regexp [<name>] <field> <regexp>
 
 Like `header`, but supports regular expressions. Capture groups can be accessed via placeholder like `{http.regexp.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
 
+Only one regular expression is supported per header field. Multiple different fields will be AND'ed.
+
 #### Example:
 
 Match requests where the Cookie header contains `login_` followed by a hex string, with a capture group that can be accessed with `{http.regexp.login.1}`.
@@ -285,6 +297,8 @@ host <hosts...>
 
 Matches request by the `Host` header field of the request. It is not common to use this in the Caddyfile, since most site blocks already indicate hosts in the address of the site. This matcher is mostly used in site blocks that don't define specific hostnames.
 
+Multiple `host` matchers will be OR'ed together.
+
 #### Example:
 
 ```caddy-d
@@ -301,6 +315,8 @@ method <verbs...>
 
 By the method (verb) of the HTTP request. Verbs should be uppercase, like `POST`. Can match one or many methods.
 
+Multiple `method` matchers will be OR'ed together.
+
 #### Examples:
 
 Match requests with the `GET` method.
@@ -380,6 +396,8 @@ By request path, meaning the path component of the request's URI. Path matches a
 - On both sides, for a substring match (`*/contains/*`)
 - In the middle, for a globular match (`/accounts/*/info`)
 
+Multiple `path` matchers will be OR'ed together.
+
 
 ---
 ### path_regexp
@@ -390,6 +408,8 @@ path_regexp [<name>] <regexp>
 
 Like `path`, but supports regular expressions. Capture groups can be accessed via placeholder like `{http.regexp.name.capture_group}` where `name` is the name of the regular expression (optional, but recommended) and `capture_group` is either the name or number of the capture group in the expression. Capture group `0` is the full regexp match, `1` is the first capture group, `2` is the second capture group, and so on.
 
+There can only be one `path_regexp` matcher per named matcher.
+
 #### Example:
 
 Match requests where the path ends a 6 character hex string followed by `.css` or `.js` as the file extension, with capture groups that can be accessed with `{http.regexp.static.1}` and `{http.regexp.static.2}` for each part enclosed in `( )`, respectively.
@@ -408,6 +428,8 @@ protocol http|https|grpc
 
 By request protocol.
 
+There can only be one `protocol` matcher per named matcher.
+
 
 ---
 ### query
@@ -416,7 +438,9 @@ By request protocol.
 query <key>=<val>...
 ```
 
-By query string parameters. Should be a sequence of `key=value` pairs. Keys are matched exactly, case-sensitively. Values are matched exactly, but also support `*` to match any value.
+By query string parameters. Should be a sequence of `key=value` pairs. Keys are matched exactly, case-sensitively. Values can contain placeholders. Values are matched exactly, but also support `*` to match any value.
+
+There can be multiple `query` matchers per named matcher, and pairs with the same keys will be OR'ed together.
 
 #### Example:
 
@@ -436,6 +460,8 @@ remote_ip <ranges...>
 
 By remote (client) IP address. If `X-Forwarded-For` is passed in request headers, this will be used for remote IP address. Accepts exact IPs or CIDR ranges.
 
+Multiple `remote_ip` matchers will be OR'ed together.
+
 #### Example:
 
 Match requests from private IPv4 addresses.