Merge branch 'improve_user_scan_meta_doc' into 'master'

doc: improve documentation about 'user_scan_meta'

See merge request !4631

doc/docs/data/data_scan_metadata.md

@@ -23,7 +23,20 @@ You can register metadata generators in the setup of a BLISS session, which will
 
 The `get_user_scan_meta()` function from `bliss.scanning.scan_meta` returns the
 scan metadata object. Each metadata category is accessible via the corresponding property.
-Then, the `.set()` method allows to associate a name or an object with a `.name` property
+
+The metadata category has a `timing` property, which allows to select when metadata has
+to be taken. `timing` can be a combination of:
+
+- `scan_meta.META_TIMING.START`
+    - will be called at the beginning of the scan
+- `scan_meta.META_TIMING.END`
+    - will be called at the end of the scan
+- `scan_meta.META_TIMING.PREPARED`
+    - will be called when the scan has been prepared (not started yet)
+
+Default timing in general is START. Default timing for `instrument` category is END.
+
+Then, the `.set()` method allows to associate a name (or an object with a `.name` property)
 to a function, that has to return a dictionary to be stored as metadata for the object,
 for the category.
 
@@ -59,3 +72,12 @@ scan_meta_obj.instrument.set("mymetadata", {"myattenuator":
      "thickness": 20.,
      "thickness@units": "um")
 ```
+
+!!! note
+    User scan meta are collected **for each scan**. In particular, in case of dynamic metadata (when a
+    callback function returns a dictionary), the scan object is passed to be able to
+    select whether metadata has to be returned or not.
+
+!!! note
+    Do not forget to remove items, if they are not needed. This can be done with `.remove()` on
+    the different categories.