Merge changes I409485ea,Ia330dbbd

* changes:
  Ignore invalid globs in OWNERS files
  Fix parsing of globs that contain commas

resources/Documentation/path-expressions.md

diff --git a/resources/Documentation/path-expressions.md b/resources/Documentation/path-expressions.md
index 7b976ef..a8fc387 100644
--- a/resources/Documentation/path-expressions.md
+++ b/resources/Documentation/path-expressions.md
@@ -9,8 +9,9 @@
 
 * [find-owners](backend-find-owners.html) backend:
   uses [globs](#globs), but each glob is automatically prefixed with `{**/,}`
-  so that subfolders are always matched (e.g. `*.md` matches all md files in all
-  subfolders, rather then only md files in the current folder)
+  so that subfolders are always matched, e.g. `*.md` matches all md files in all
+  subfolders, rather then only md files in the current folder (also see the
+  [caveat](#findOwnersCaveat) section below)
 * [proto](backend-proto.html) backend:
   uses [simple path expressions](#simplePathExpressions)
 
@@ -40,15 +41,17 @@
 
 | To Match | Glob | find-owners | Simple Path Expression |
 | -------- | ---- | ----------- | ---------------------- |
-| Concrete file in current folder | `BUILD` | not possible (1) | `BUILD` |
-| File type in current folder | `*.md` | not possible (1) | `*.md` |
+| Concrete file in current folder | `BUILD` | [not possible](#findOwnersCaveatMatchingAFile) | `BUILD` |
+| File type in current folder | `*.md` | [not possible](#findOwnersCaveatMatchingFilesByType) | `*.md` |
 | Concrete file in the current folder and in all subfolders | `{**/,}BUILD` | `BUILD` | needs 2 expressions: `BUILD` + `.../BUILD` |
 | File type in the current folder and in all subfolders | `**.md` | `*.md` or `**.md` | `....md` |
-| All files in a subfolder | `my-folder/**` | not possible (1), but you can add a `my-folder/OWNERS` file instead of using a glob | `my-folder/...` |
+| All files in a subfolder | `my-folder/**` | [not possible](#findOwnersCaveatMatchingFilesInSubfolder), but you can add a `my-folder/OWNERS` file instead of using a glob | `my-folder/...` |
 | All “foo-<1-digit-number>.txt” files in all subfolders | `{**/,}foo-[0-9].txt` | `foo-[0-9].txt` |not possible |
 | All “foo-<n-digit-number>.txt” files in all subfolders | not possible | not possible | not possible
 
-(1): To be compatible with the `find-owners` plugin find-owners path expressions
+## <a id="findOwnersCaveat">Caveat with find-owners path expressions
+
+To be compatible with the `find-owners` plugin find-owners path expressions
 are prefixes with `{**/,}` which matches any folder (see
 [above](path-expressions.html)). This means if path expressions like  `BUILD`,
 `*.md` or `my-folder/**` are used in `OWNERS` files the effective path
@@ -58,6 +61,41 @@
 `my-folder/**` in any subfolder (e.g. `foo/bar/BUILD`, `foo/bar/baz.md` and
 `foo/bar/my-folder/`).
 
+### Examples
+
+#### <a id="findOwnersCaveatMatchingAFile">Matching a file
+
+If you have the following `/foo/OWNERS` file:
+
+```
+  per-file BUILD=john.doe@example.com
+```
+\
+John Doe owns the `/foo/BUILD` file, but also all `BUILD` files in
+subfolders of `/foo/`, e.g. `/foo/bar/baz/BUILD`.
+
+#### <a id="findOwnersCaveatMatchingFilesByType">Matching files by type
+
+If you have the following `/foo/OWNERS` file:
+
+```
+  per-file *.md=john.doe@example.com
+```
+\
+John Doe owns all `*.md` files in `/foo/`, but also all `*.md` files in
+subfolders of `/foo/`, e.g. `/foo/bar/baz.md`.
+
+#### <a id="findOwnersCaveatMatchingFilesInSubfolder">Matching files in subfolder
+
+If you have the following `/foo/OWNERS` file:
+
+```
+  per-file my-folder/*=john.doe@example.com
+```
+\
+John Doe owns all files in the `/foo/my-folder/` folder, but also all files in
+any `my-folder/` subfolder, e.g. all files in `/foo/bar/baz/my-folder/`.
+
 ---
 
 Back to [@PLUGIN@ documentation index](index.html)