Add more gn documentation

tools/gn/ninja_build_writer.cc

Index: tools/gn/ninja_build_writer.cc
diff --git a/tools/gn/ninja_build_writer.cc b/tools/gn/ninja_build_writer.cc
index 74a77878c42492afba7a9902aa3128a9506a3d17..2f2336cde034b77baf63cfcc8963f195b51347b5 100644
--- a/tools/gn/ninja_build_writer.cc
+++ b/tools/gn/ninja_build_writer.cc
@@ -341,6 +341,53 @@ bool NinjaBuildWriter::WriteSubninjas(Err* err) {
   return true;
 }
 
+const char kNinjaRules_Help[] =
+    R"(Ninja build rules
+
+The "all" and "default" rules
+
+  All generated targets (see "gn help execution") will be added to an implicit
+  build rule called "all" so "ninja all" will always compile everything. The
+  default rule will be used by Ninja if no specific target is specified (just
+  typing "ninja"). If there is a target named "//:default" it will be the
+  default build rule, otherwise the implicit "all" rule will be used.
+
+Phony rules
+
+  GN generates Ninja "phony" rules for targets in the default toolchain.  The
+  phony rules can collide with each other and with the names of generated files
+  so are generated with the following priority:
+
+    1. Actual files generated by the build always take precedence.
+
+    2. Targets in the toplevel //BUILD.gn file.
+
+    3. Targets in toplevel directories matching the names of the directories.
+       So "ninja foo" can be used to compile "//foo:foo". This only applies to
+       the first level of directories since usually these are the most
+       important (so this won't apply to "//foo/bar:bar").
+
+    4. The short names of executables if there is only one executable with that
+       short name. Use "ninja doom_melon" to compile the
+       "//tools/fruit:doom_melon" executable.
+
+    5. The short names of all targets if there is only one target with that
+       short name.
+
+    6. Full label name with no leading slashes. So you can use
+       "ninja tools/fruit:doom_melon" to build "//tools/fruit:doom_melon".
+
+    7. Labels with an implicit name part (when the short names match the
+       directory). So you can use "ninja foo/bar" to compile "//foo/bar:bar".
+
+  These "phony" rules are provided only for running Ninja since this matches
+  people's historical expectations for building. For consistency with the rest
+  of the program, GN introspection commands accept explicit labels.
+
+  To explicitly compile a target in a non-default toolchain, you must give
+  Ninja the exact name of the output file relative to the build directory.
+)";
+
 bool NinjaBuildWriter::WritePhonyAndAllRules(Err* err) {
   // Track rules as we generate them so we don't accidentally write a phony
   // rule that collides with something else.
@@ -363,6 +410,10 @@ bool NinjaBuildWriter::WritePhonyAndAllRules(Err* err) {
   std::map<std::string, Counts> short_names;
   std::map<std::string, Counts> exes;
 
+  // ----------------------------------------------------
+  // If you change this algorithm, update the help above!
+  // ----------------------------------------------------
+
   for (const Target* target : default_toolchain_targets_) {
     const Label& label = target->label();
     const std::string& short_name = label.name();
@@ -471,12 +522,6 @@ bool NinjaBuildWriter::WritePhonyAndAllRules(Err* err) {
           written_rules.insert(medium_name).second)
         WritePhonyRule(target, medium_name);
     }
-
-    // Write the short name if no other target shares that short name and
-    // non of the higher-priority rules above claimed it.
-    if (short_names[label.name()].count == 1 &&
-        written_rules.insert(label.name()).second)
-      WritePhonyRule(target, label.name());
   }
 
   // Write the autogenerated "all" rule.