Improve docstring for emit

[sed-i]

Iiuc, emission of custom events does not get queued: when they are emitted, their handler is called immediately, before the previous hook finished.

operator/ops/framework.py

Lines 331 to 335 in 26c6e95

	def emit(self, *args: Any, **kwargs: Any):
	"""Emit event to all registered observers.
	The current storage state is committed before and after each observer is notified.
	"""

I.e. emission is nested, not sequential.

1. Hook 1
2.   Hook 2
3.     Hook 3
4.   Finish hook 2 handler
5. Finish hook 1 handler

Could be handy to have it outlined in the docs.

[benhoyt]

@sed-i Would you be willing to suggest a concrete docstring change?

[sed-i]

How about:

         """Emit event to all registered observers. 
  
         The current storage state is committed before and after each observer is notified. 
+        Note that emission of custom events is handled immediately. This means that a call to
+        `emit` is followed by immediately calling the observers. In other words, emission of
+        custom events is not queued but rather nested. For example:
+        1. Core hook (emits custom_event_1)
+        2.   Custom event 1 handler (emits custom_event_2)
+        3.     Custom event 2 handler
+        4.   Resume custom event 1 handler
+        5. Resume core hook handler
         """ 

[benhoyt]

Thanks, done in #1072.

I've basically taken your suggestion above, but removed the middle sentence as I thought that was basically repeating the same thing.