Enhance GN diagnostic tools

tools/gn/functions.cc

Index: tools/gn/functions.cc
diff --git a/tools/gn/functions.cc b/tools/gn/functions.cc
index 35e42d44e98a739179ab0a4e474f4c2c64dd97f3..788b06fadc546e732dab735ffc1acf5d6425e612 100644
--- a/tools/gn/functions.cc
+++ b/tools/gn/functions.cc
@@ -489,8 +489,6 @@ const char kSetSourcesAssignmentFilter_Help[] =
     "  example, you may want to filter out all \"*_win.cc\" files on non-\n"
     "  Windows platforms.\n"
     "\n"
-    "  See \"gn help patterns\" for specifics on patterns.\n"
-    "\n"
     "  Typically this will be called once in the master build config script\n"
     "  to set up the filter for the current platform. Subsequent calls will\n"
     "  overwrite the previous values.\n"
@@ -499,9 +497,45 @@ const char kSetSourcesAssignmentFilter_Help[] =
     "  be filtered out, call set_sources_assignment_filter([]) to clear the\n"
     "  list of filters. This will apply until the current scope exits\n"
     "\n"
-    "Example:\n"
+    "How to use patterns\n"
+    "\n"
+    "  File patterns are VERY limited regular expressions. They must match\n"
+    "  the entire input string to be counted as a match. In regular\n"
+    "  expression parlance, there is an implicit \"^...$\" surrounding your\n"
+    "  input. If you want to match a substring, you need to use wildcards at\n"
+    "  the beginning and end.\n"
+    "\n"
+    "  There are only two special tokens understood by the pattern matcher.\n"
+    "  Everything else is a literal.\n"
+    "\n"
+    "   * Matches zero or more of any character. It does not depend on the\n"
+    "     preceding character (in regular expression parlance it is\n"
+    "     equivalent to \".*\").\n"
+    "\n"
+    "  \\b Matches a path boundary. This will match the beginning or end of\n"
+    "     a string, or a slash.\n"
+    "\n"
+    "Pattern examples\n"
+    "\n"
+    "  \"*asdf*\"\n"
+    "      Matches a string containing \"asdf\" anywhere.\n"
+    "\n"
+    "  \"asdf\"\n"
+    "      Matches only the exact string \"asdf\".\n"
+    "\n"
+    "  \"*.cc\"\n"
+    "      Matches strings ending in the literal \".cc\".\n"
+    "\n"
+    "  \"\\bwin/*\"\n"
+    "      Matches \"win/foo\" and \"foo/win/bar.cc\" but not \"iwin/foo\".\n"
+    "\n"
+    "Sources assignment example\n"
+    "\n"
     "  # Filter out all _win files.\n"
-    "  set_sources_assignment_filter([ \"*_win.cc\", \"*_win.h\" ])\n";
+    "  set_sources_assignment_filter([ \"*_win.cc\", \"*_win.h\" ])\n"
+    "  sources = [ \"a.cc\", \"b_win.cc\" ]\n"
+    "  print(sources)\n"
+    "  # Will print [ \"a.cc\" ]. b_win one was filtered out.\n";
 
 Value RunSetSourcesAssignmentFilter(Scope* scope,
                                     const FunctionCallNode* function,