[Feature Request]: Improve return/yield documentation

[damccorm]

What would you like to happen?

We partially doc this here - https://beam.apache.org/documentation/programming-guide/#:~:text=Inside%20your,incorrect%20behavior. - but we should:

1. Add examples of return/yield used differently (e.g. what happens if you return a list vs a single element vs yielding each)
2. Change some of the examples in the beam repo to use yield instead of return

Issue Priority

Priority: 2 (default / most feature requests should be filed as P2)

Issue Components

• Component: Python SDK
• Component: Java SDK
• Component: Go SDK
• Component: Typescript SDK
• Component: IO connector
• Component: Beam YAML
• Component: Beam examples
• Component: Beam playground
• Component: Beam katas
• Component: Website
• Component: Infrastructure
• Component: Spark Runner
• Component: Flink Runner
• Component: Samza Runner
• Component: Twister2 Runner
• Component: Hazelcast Jet Runner
• Component: Google Cloud Dataflow Runner

[YashaswiniTB]

@damccorm This is my first contribution to open source. I've tried my best to understand the context and update the documentation accordingly. Kindly review it, and please feel free to correct me if anything needs improvement. I’m eager to learn and contribute better. Thank you!

[rakeshcusat]

@damccorm I have run into similar issue and end up spending hours debugging some of the code examples. It would be a great help to others if they have access to accurate documentation. I am happy to provide help here.

@YashaswiniTB can you share your PR?

[damccorm]

@damccorm I have run into similar issue and end up spending hours debugging some of the code examples. It would be a great help to others if they have access to accurate documentation. I am happy to provide help here.

@YashaswiniTB can you share your PR?

Yeah, this is for sure a pain - any input you have from your experience would be helpful! The PR is #34912