Document kwargs with examples
@@ -119,6 +119,25 @@ Please note that it is not necessary the same selector as used in the decorator,
as one selector can match multiple actual resources.
``body`` is the handled object's body, a read-only mapping (dict).
+It might look like this as an example:
+
+.. code-block:: python
+
+ {
+ 'apiVersion': 'kopf.dev/v1',
+ 'kind': 'KopfExample',
+ 'metadata': {
+ 'name': 'kopf-example-1',
+ 'namespace': 'default',
+ 'uid': '1234-5678-...',
+ },
+ 'spec': {
+ 'field': 'value',
+ },
+ 'status': {
+ ...
+ },
+ }
``spec``, ``meta``, ``status`` are aliases for relevant stanzas, and are
live-views into ``body['spec']``, ``body['metadata']``, ``body['status']``.
@@ -156,6 +175,16 @@ after the handler. It is actively used internally by the framework itself,
and is shared to the handlers for convenience _(since patching happens anyway
in the framework, why make separate API calls for patching?)_.
+.. note::
+ Currently, it is just a dictionary, and the changes are applied
+ as ``application/merge-patch+json``: ``None`` values delete the fields,
+ other values override, dicts are merged.
+
+ In the future, at discretion of this framework, it can be converted
+ to JSON-patch (a list of add/change/remove operation), while keeping
+ the same Python mutable mapping protocol and remembering the changes
+ in the order they were made.
+
.. kwarg:: memo
@@ -239,8 +268,20 @@ Diffing
``old`` & ``new`` are the old & new state of the object or a field within
the detected changes. The new state usually corresponds to :kwarg:`body`.
+For the whole-object handlers, ``new`` is an equivalent of :kwarg:`body`.
+For the field handlers, it is the value of that field specifically.
+
``diff`` is a list of changes of the object between old & new states.
+The diff highlights which keys were added, changed, or removed
+in the dictionary, with old & new values being selectable,
+and generally ignores all other fields that were not changed.
+
+Due to specifics of Kubernetes, ``None`` is interpreted as absence
+of the value/field, not as a value of its own kind. In case of diffs,
+it means that the value did not exist before, or will not exist after
+the changes (for the old & new value positions respectively):
+
Resource daemon kwargs
======================
