Add more gn documentation

tools/gn/ninja_build_writer.cc

 // Copyright (c) 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #include "tools/gn/ninja_build_writer.h"
 
 #include <stddef.h>
 
 #include <fstream>
 #include <map>
@@ skipping 323 matching lines @@
     out_ << "subninja ";
     path_output_.WriteFile(out_, subninja);
     out_ << std::endl;
     previous_subninja = subninja;
     previous_toolchain = pair.second;
   }
   out_ << std::endl;
   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.
   // GN internally generates an "all" target, so don't duplicate it.
   base::hash_set<std::string> written_rules;
   written_rules.insert("all");
 
   // Set if we encounter a target named "//:default".
   bool default_target_exists = false;
 
   // Targets in the root build file.
   std::vector<const Target*> toplevel_targets;
 
   // Targets with names matching their toplevel directories. For example
   // "//foo:foo". Expect this is the naming scheme for "big components."
   std::vector<const Target*> toplevel_dir_targets;
 
   // Tracks the number of each target with the given short name, as well
   // as the short names of executables (which will be a subset of short_names).
   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();
 
     if (label.dir().value() == "//" && label.name() == "default")
       default_target_exists = true;
 
     // Count the number of targets with the given short name.
     Counts& short_names_counts = short_names[short_name];
     short_names_counts.count++;
@@ skipping 88 matching lines @@
     // (e.g. "//foo/bar:bar" -> "foo/bar").
     if (FindLastDirComponent(label.dir()) == label.name()) {
       std::string medium_name = DirectoryWithNoLastSlash(label.dir());
       base::TrimString(medium_name, "/", &medium_name);
       // That may have generated a name the same as the short name of the
       // target which we already wrote.
       if (medium_name != label.name() &&
           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.
   if (!default_toolchain_targets_.empty()) {
     out_ << "\nbuild all: phony";
 
     EscapeOptions ninja_escape;
     ninja_escape.mode = ESCAPE_NINJA;
     for (const Target* target : default_toolchain_targets_) {
       out_ << " $\n    ";
@@ skipping 15 matching lines @@
   EscapeOptions ninja_escape;
   ninja_escape.mode = ESCAPE_NINJA;
 
   // Escape for special chars Ninja will handle.
   std::string escaped = EscapeString(phony_name, ninja_escape, nullptr);
 
   out_ << "build " << escaped << ": phony ";
   path_output_.WriteFile(out_, target->dependency_output_file());
   out_ << std::endl;
 }