Improve docs for set vs put and put_complete

[wakonig]

closes #44

[github-actions]

Remaining TODOs in the docs:

docs/how-to/devices/add-an-epics-motor.md:<!-- TODO: Add video here -->
docs/getting-started/quick-start/04-run-your-first-scan.md:<!-- TODO: link to learn about signals -->
docs/getting-started/quick-start/01-open-bec.md:<!-- TODO: link to different application modes. -->
docs/getting-started/quick-start/01-open-bec.md:<!-- TODO: link to information about deployments. -->
docs/getting-started/next-steps/script-gui-interactions.md:TODO: Revisit as a dedicated, safety-reviewed scripting tutorial.

[xiaoqiangwang]

Good digging. The description table of how put_complete affects set is accurate.

When comparing set and put, maybe make it clear that set calls put.

put is a direct wrapper of epics.PV.put. The only difference is that the use_complete defaults to put_complete if not specified.

[xiaoqiangwang]

Another thought comes to my mind: the doc is about accessing the ophyd signals directly (RPC to device server or in the device server). When user is in BEC client, the proxy object takes over and has different signature.

[xiaoqiangwang]

If you want to put an example how put_complete changes the wait behavior. The Acquire record in an areaDetector IOC (acquire signal in an areaDetector camera object, cam.acquire) calls back when acquisition finishes. e.g.

# without `put_complete=False` the status wait returns immediately
# because it checks the Acquire PV  value has changed to 1.
>> acquire = EpicsSignal('X04SA-ES3-EIGER:cam1:Acquire', name='acquire')
>> acquire.set(1).wait()

# with `put_complete=True` the status wait returns only when camera finishes acquisition.
>> acquire = EpicsSignal('X04SA-ES3-EIGER:cam1:Acquire', name='acquire', put_complete=True)
>> acquire.set(1).wait()

The same applies to the motor record .VAL field, .e.g. user_setpoint signal in EpicsMotor ophyd object.

Whether a potentially long process trigger record will callback depends on the underlying EPICS integration. The above example is an effective way to find out.