GN documentation updates.

Mark the "copy" target as a target function so it appears in the correct section of "gn help".

Use get_target_outputs() in the template example, since you should generall do this instead of process_file_template.

Update docs for process_file_template to state that you should use get_target_outputs if possible.

R=cjhopman@chromium.org

Review URL: https://codereview.chromium.org/270613006

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@269793 0039d316-1c4b-4281-b951-d872f2087c98

tools/gn/function_process_file_template.cc

@@ -20,6 +20,11 @@ const char kProcessFileTemplate_Help[] =
     "  returning the result of applying each template to each source. This is\n"
     "  typically used for computing output file names from input files.\n"
     "\n"
+    "  In most cases, get_target_outputs() will give the same result with\n"
+    "  shorter, more maintainable code. This function should only be used\n"
+    "  when that function can't be used (like there's no target or the target\n"
+    "  is defined in another build file).\n"
+    "\n"
     "Arguments:\n"
     "\n"
     "  The source_list is a list of file names.\n"

tools/gn/function_template.cc

@@ -83,18 +83,17 @@ const char kTemplate_Help[] =
     "    assert(defined(invoker.sources),\n"
     "           \"Need sources in $target_name listing the idl files.\")\n"
     "\n"
-    "    # Define a variable containing a source expansion\n"
-    "    # (see \"gn help source_expansion\") that maps input files to\n"
-    "    # output files. It is used in both targets below.\n"
-    "    filter = [ \"$target_gen_dir/{{source_name_part}}.cc\",\n"
-    "               \"$target_gen_dir/{{source_name_part}}.h\" ]\n"
+    "    # Name of the intermediate target that does the code gen. This must\n"
+    "    # incorporate the target name so it's unique across template\n"
+    "    # instantiations.\n"
+    "    code_gen_target_name = target_name + \"_code_gen\"\n"
     "\n"
     "    # Intermediate target to convert IDL to C source. Note that the name\n"
     "    # is based on the name the invoker of the template specified. This\n"
     "    # way, each time the template is invoked we get a unique\n"
     "    # intermediate action name (since all target names are in the global\n"
     "    # scope).\n"
-    "    action_foreach(\"${target_name}_code_gen\") {\n"
+    "    action_foreach(code_gen_target_name) {\n"
     "      # Access the scope defined by the invoker via the implicit\n"
     "      # \"invoker\" variable.\n"
     "      sources = invoker.sources\n"
@@ -106,20 +105,24 @@ const char kTemplate_Help[] =
     "      # to reference a script relative to the template file, we'll need\n"
     "      # to use an absolute path instead.\n"
     "      script = \"//tools/idl/idl_code_generator.py\"\n"
-    "      outputs = filter  # Variable from above.\n"
+    "\n"
+    "      # Tell GN how to expand output names given the sources.\n"
+    "      # See \"gn help source_expansion\" for more.\n"
+    "      outputs = [ \"$target_gen_dir/{{source_name_part}}.cc\",\n"
+    "                  \"$target_gen_dir/{{source_name_part}}.h\" ]\n"
     "    }\n"
     "\n"
     "    # Name the source set the same as the template invocation so\n"
     "    # instancing this template produces something that other targets\n"
     "    # can link to in their deps.\n"
     "    source_set(target_name) {\n"
-    "      # Generates the list of sources.\n"
-    "      # See \"gn help process_file_template\"\n"
-    "      sources = process_file_template(invoker.sources, filter)\n"
+    "      # Generates the list of sources, we get these from the\n"
+    "      # action_foreach above.\n"
+    "      sources = get_target_outputs(\":$code_gen_target_name\")\n"
     "\n"
     "      # This target depends on the files produced by the above code gen\n"
     "      # target.\n"
-    "      deps = [ \":${target_name}_code_gen\" ]\n"
+    "      deps = [ \":$code_gen_target_name\" ]\n"
     "    }\n"
     "  }\n"
     "\n"

tools/gn/functions.cc

@@ -638,6 +638,7 @@ struct FunctionInfoInitializer {
     INSERT_FUNCTION(Action, true)
     INSERT_FUNCTION(ActionForEach, true)
     INSERT_FUNCTION(Component, true)
+    INSERT_FUNCTION(Copy, true)
     INSERT_FUNCTION(Executable, true)
     INSERT_FUNCTION(Group, true)
     INSERT_FUNCTION(SharedLibrary, true)
@@ -647,7 +648,6 @@ struct FunctionInfoInitializer {
 
     INSERT_FUNCTION(Assert, false)
     INSERT_FUNCTION(Config, false)
-    INSERT_FUNCTION(Copy, false)
     INSERT_FUNCTION(DeclareArgs, false)
     INSERT_FUNCTION(Defined, false)
     INSERT_FUNCTION(ExecScript, false)