davidradl commented on code in PR #27201:
URL: https://github.com/apache/flink/pull/27201#discussion_r2498265035
##########
docs/content/docs/dev/datastream/operators/overview.md:
##########
@@ -676,16 +676,16 @@ some_stream.filter(...).slot_sharing_group("name")
{{< /tabs>}}
## Name And Description
-Operators and job vertices in flink have a name and a description.
-Both name and description are introduction about what an operator or a job
vertex is doing, but they are used differently.
+Operators and job vertices in Flink have a name and a description.
+While the name and description both explain what an operator or a job vertex
is doing, they are used differently.
-The name of operator and job vertex will be used in web ui, thread name,
logging, metrics, etc.
-The name of a job vertex is constructed based on the name of operators in it.
+Operator and job vertex names are used in the web UI, thread name, logging,
metrics, etc.
+The name of a job vertex is constructed using the names of operators it
contains.
The name needs to be as concise as possible to avoid high pressure on external
systems.
The description will be used in the execution plan and displayed as the
details of a job vertex in web UI.
-The description of a job vertex is constructed based on the description of
operators in it.
-The description can contain detail information about operators to facilitate
debugging at runtime.
+The description of a job vertex is constructed using the descriptions of the
operators it contains.
+The description can contain detailed information about operators to facilitate
debugging at runtime.
Review Comment:
when we say "is constructed" do we mean that Flink code constructs it, or
user code? If it is Flink code then we should give an example of how the
descriptions are constructed. If is is user code then we should make it
obvious from the wording that this is advice / good practise around description
content.
The line above "The name needs to be as concise as possible to avoid high
pressure on external systems." I would suggest changing this to something like
, the name should be descriptive, unique (within what ever scope); and concise
(why does a long name create high pressure on external systems?)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
