Improve traffic annotation documentation
Specific improvements:
* refer to proto attribute names, rather than their types (to keep
things consistent with elsewhere in the file)
* provide a reference to the actual proto definition that these
attributes come from
* include a full path to `chrome_settings.proto`
Change-Id: I74d962ceb6c4ffdaf246ed091cc5a486ff34d779
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/3370786
Reviewed-by: Ramin Halavati <[email protected]>
Commit-Queue: Glenn Hartmann <[email protected]>
Cr-Commit-Position: refs/heads/main@{#956507}
diff --git a/docs/network_traffic_annotations.md b/docs/network_traffic_annotations.md
index 6a66463..b9c7f0e 100644
--- a/docs/network_traffic_annotations.md
+++ b/docs/network_traffic_annotations.md
@@ -83,7 +83,9 @@
create a network request.
### Content of Annotation Tag
-Each network traffic annotation should specify the following items:
+Each network traffic annotation should specify the following items, as defined
+in the `NetworkTrafficAnnotation` message of
+`chrome/browser/privacy/traffic_annotation.proto`:
* `uniqueÙ€id`: A globally unique identifier that must stay unchanged while the
network request carries the same semantic meaning. If the network request gets
a new meaning, this ID needs to be changed. The purpose of this ID is to give
@@ -92,10 +94,10 @@
with a network request). IDs of one component should have a shared prefix so
that sorting all NetworkTrafficAnnotations by unique_id groups those that
belong to the same component together.
-* `TrafficSource`: These set of fields specify the location of annotation in
+* `source`: These set of fields specify the location of annotation in
the source code. These fields are automatically set and do not need
specification.
-* `TrafficSemantics`: These set of fields specify meta information about the
+* `semantics`: These set of fields specify meta information about the
network request’s content and reason.
* `sender`: What component triggers the request. The components should be
human readable and don’t need to reflect the components/ directory. Avoid
@@ -123,7 +125,7 @@
field.
* `destination_other`: Human readable description in case the destination
points to `OTHER`.
-* `TrafficPolicy`: These set of fields specify the controls that a user may have
+* `policy`: These set of fields specify the controls that a user may have
on disabling or limiting the network request and its trace.
* `cookies_allowed`: Specifies if this request stores and uses cookies or
not. Use values `YES` or `NO`.
@@ -146,7 +148,9 @@
description works everywhere!
* `chrome_policy`: Policy configuration that disables or limits this network
request. This would be a text serialized protobuf of any enterprise policy.
- See policy list or chrome_settings.proto for the full list of policies.
+ See policy list or
+ `out/Debug/gen/components/policy/proto/chrome_settings.proto` for the full
+ list of policies.
* `policy_exception_justification`: If there is no policy to disable or limit
this request, a justification can be presented here.
* `comments`: If required, any human readable extra comments.
