Document op and matcher mappings

lib/src/filter/tagged.rs

@@ -37,7 +37,7 @@ pub mod swaplock;
 /// parsed from a textual format:
 ///
 /// ```text
-/// {Matcher}{Op}{Value}
+/// [!]{Matcher}{Op}{Value}
 /// ```
 ///
 /// For example:
@@ -46,6 +46,7 @@ pub mod swaplock;
 /// path==/foo/bar
 /// path*=**/bar
 /// path~=bar$
+/// !kind=file
 /// ```
 ///
 /// There is a set of [operators][Op]:
@@ -56,15 +57,35 @@ pub mod swaplock;
 ///
 /// Sets are a list of values separated by `,`.
 ///
-/// In addition to the two-symbol operators, there is the `=` "auto" operator, which attempts to
-/// figure out which operator to use based on the _matcher_: glob for paths, exact for anything else.
-/// Note that this detection may change, with a semver approach: whenever possible existing usage
-/// should keep working.
+/// In addition to the two-symbol operators, there is the `=` "auto" operator, which maps to the
+/// most convenient operator for the given _matcher_. The current mapping is:
+///
+/// | Matcher                                         | Operator      |
+/// |-------------------------------------------------|---------------|
+/// | [Tag](Matcher::Tag)                             | `:=` (in set) |
+/// | [Path](Matcher::Path)                           | `*=` (glob)   |
+/// | [FileType](Matcher::FileType)                   | `:=` (in set) |
+/// | [FileEventKind](Matcher::FileEventKind)         | `*=` (glob)   |
+/// | [Source](Matcher::Source)                       | `:=` (in set) |
+/// | [Process](Matcher::Process)                     | `:=` (in set) |
+/// | [Signal](Matcher::Signal)                       | `:=` (in set) |
+/// | [ProcessCompletion](Matcher::ProcessCompletion) | `:=` (in set) |
 ///
 /// [Matchers][Matcher] correspond to Tags, but are not one-to-one: the `path` matcher operates on
 /// the `path` part of the `Path` tag, and the `type` matcher operates on the `file_type`, for
 /// example.
 ///
+/// | Matcher                            | Syntax   | Tag                                          |
+/// |------------------------------------|----------|----------------------------------------------|
+/// | [Tag](Matcher::Tag)                | `tag`    | _the presence of a Tag on the event_         |
+/// | [Path](Matcher::Path)              | `path`   | [Path](Tag::Path) (`path` field)             |
+/// | [FileType](Matcher::FileType)      | `type`   | [Path](Tag::Path) (`file_type` field, when Some) |
+/// | [FileEventKind](Matcher::FileEventKind) | `kind` or `fek` | [FileEventKind](Tag::FileEventKind) |
+/// | [Source](Matcher::Source)          | `source` or `src`  | [Source](Tag::Source)              |
+/// | [Process](Matcher::Process)        | `process` or `pid` | [Process](Tag::Process)            |
+/// | [Signal](Matcher::Signal)          | `signal` | [Signal](Tag::Signal)                        |
+/// | [ProcessCompletion](Matcher::ProcessCompletion) | `complete` or `exit` | [ProcessCompletion](Tag::ProcessCompletion) |
+///
 /// Filters are checked in order, grouped per tag and per matcher. Filter groups may be checked in
 /// any order, but the filters in the groups are checked in add order. Path glob filters are always
 /// checked first, for internal reasons.

lib/tests/filter_tagged_parser.rs

@@ -45,12 +45,26 @@ fn path_auto_op() {
 }
 
 #[test]
-fn other_auto_op() {
+fn fek_auto_op() {
 	assert_eq!(
-		filter("kind=foo"),
+		filter("fek=foo"),
 		Filter {
 			in_path: None,
 			on: Matcher::FileEventKind,
+			op: Op::Glob,
+			pat: Pattern::Glob("foo".to_string()),
+			negate: false,
+		}
+	);
+}
+
+#[test]
+fn other_auto_op() {
+	assert_eq!(
+		filter("type=foo"),
+		Filter {
+			in_path: None,
+			on: Matcher::FileType,
 			op: Op::InSet,
 			pat: Pattern::Set(HashSet::from(["foo".to_string()])),
 			negate: false,