💹 Update GN docs about target_cpu to encourage use of current_cpu

tools/gn/variables.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/variables.h"
 
 namespace variables {
 
 // Built-in variables ----------------------------------------------------------
 
@@ skipping 34 matching lines @@
     "  - \"win\"\n";
 
 const char kTargetCpu[] = "target_cpu";
 const char kTargetCpu_HelpShort[] =
     "target_cpu: [string] The desired cpu architecture for the build.";
 const char kTargetCpu_Help[] =
     "target_cpu: The desired cpu architecture for the build.\n"
     "\n"
     "  This value should be used to indicate the desired architecture for\n"
     "  the primary objects of the build. It will match the cpu architecture\n"
-    "  of the default toolchain.\n"
+    "  of the default toolchain, but not necessarily the current toolchain.\n"
     "\n"
     "  In many cases, this is the same as \"host_cpu\", but in the case\n"
-    "  of cross-compiles, this can be set to something different. This \n"
-    "  value is different from \"current_cpu\" in that it can be referenced\n"
-    "  from inside any toolchain. This value can also be ignored if it is\n"
-    "  not needed or meaningful for a project.\n"
+    "  of cross-compiles, this can be set to something different. This\n"
+    "  value is different from \"current_cpu\" in that it does not change\n"
+    "  based on the current toolchain. When writing rules, \"current_cpu\"\n"
+    "  should be used rather than \"target_cpu\" most of the time.\n"
     "\n"
     "  This value is not used internally by GN for any purpose, so it\n"
     "  may be set to whatever value is needed for the build.\n"
     "  GN defaults this value to the empty string (\"\") and the\n"
     "  configuration files should set it to an appropriate value\n"
     "  (e.g., setting it to the value of \"host_cpu\") if it is not\n"
     "  overridden on the command line or in the args.gn file.\n"
     "\n"
     "  Where practical, use one of the following list of common values:\n"
     "\n"
@@ skipping 1656 matching lines @@
     INSERT_VARIABLE(Testonly)
     INSERT_VARIABLE(Visibility)
     INSERT_VARIABLE(WriteRuntimeDeps)
   }
   return info_map;
 }
 
 #undef INSERT_VARIABLE
 
 }  // namespace variables