[FEATURE] Update the dosctring of all user-facing functions with 'examples' from the tests

[talgalili]

Problem: we need examples in the docstring, to help users understand how the functions work.
Idea: we have such examples in the test plan.
Solution: use LLM to help create examples based on the test plan (that includes correct input and output)

It's best to split into several PR.