Fixed typos and clarified generated_file docs.
Change-Id: I8dcd27281c56e9b294661429627523e75d21729a
Reviewed-on: https://gn-review.googlesource.com/c/gn/+/6302
Reviewed-by: Brett Wilson <brettw@chromium.org>
Commit-Queue: Brett Wilson <brettw@chromium.org>
diff --git a/tools/gn/metadata.cc b/tools/gn/metadata.cc
index bc4c272..b6d5076 100644
--- a/tools/gn/metadata.cc
+++ b/tools/gn/metadata.cc
@@ -11,46 +11,47 @@
Metadata is information attached to targets throughout the dependency tree. GN
allows for the collection of this data into files written during the generation
- step, enabing users to expose and aggregate this data based on the dependency
+ step, enabling users to expose and aggregate this data based on the dependency
tree.
generated_file targets
Similar to the write_file() function, the generated_file target type
creates a file in the specified location with the specified content. The
- primary difference between the function and the target type is that the
+ primary difference between write_file() and this target type is that the
write_file function does the file write at parse time, while the
generated_file target type writes at target resolution time. See
"gn help generated_file" for more detail.
- When written at target resolution time, the generated_file enables GN to
+ When written at target resolution time, generated_file enables GN to
collect and write aggregated metadata from dependents.
- A generated_file target can declare either 'contents' (to write statically
- known contents to a file) or 'data_keys'(to aggregate metadata and write the
- result to a file). It can also specify 'walk_keys' (to restrict the metadata
+ A generated_file target can declare either 'contents' to write statically
+ known contents to a file or 'data_keys' to aggregate metadata and write the
+ result to a file. It can also specify 'walk_keys' (to restrict the metadata
collection), 'output_conversion', and 'rebase'.
Collection and Aggregation
Targets can declare a 'metadata' variable containing a scope, and this
- metadata is collected and written to file by generated_file aggregation
- targets. The 'metadata' scope must contain only list values, since the
- aggregation step collects a list of these values.
+ metadata may be collected and written out to a file specified by
+ generated_file aggregation targets. The 'metadata' scope must contain
+ only list values since the aggregation step collects a list of these values.
During the target resolution, generated_file targets will walk their
dependencies recursively, collecting metadata based on the specified
'data_keys'. 'data_keys' is specified as a list of strings, used by the walk
to identify which variables in dependencies' 'metadata' scopes to collect.
- The walk begins with the listed dependencies of the 'generated_file' target,
- for each checking the "metadata" scope for any of the "data_keys". If
- present, the data in those variables is appended to the aggregate list. Note
- that this means that if more than one walk key is specified, the data in all
- of them will be aggregated into one list. From there, the walk will then
- recurse into the dependencies of each target it encounters, collecting the
- specified metadata for each.
+ The walk begins with the listed dependencies of the 'generated_file' target.
+ The 'metadata' scope for each dependency is inspected for matching elements
+ of the 'generated_file' target's 'data_keys' list. If a match is found, the
+ data from the dependent's matching key list is appended to the aggregate walk
+ list. Note that this means that if more than one walk key is specified, the
+ data in all of them will be aggregated into one list. From there, the walk
+ will then recurse into the dependencies of each target it encounters,
+ collecting the specified metadata for each.
For example:
@@ -83,10 +84,10 @@
bar.cpp
baz.cpp
- The dependency walk can be limited by using the "walk_keys". This is a list of
+ The dependency walk can be limited by using the 'walk_keys'. This is a list of
labels that should be included in the walk. All labels specified here should
also be in one of the deps lists. These keys act as barriers, where the walk
- will only recurse into targets listed here. An empty list in all specified
+ will only recurse into the targets listed. An empty list in all specified
barriers will end that portion of the walk.
group("a") {
@@ -268,4 +269,4 @@
value.origin());
}
return std::make_pair(rebased_scope_value, true);
-}
\ No newline at end of file
+}
