reread design docs and update

Author: VigneshVSV

.prettierignore

@@ -1 +1,2 @@
-docs/index.md
+docs/index.md
+docs/design/action-descriptors.md

docs/api-reference/namespaces.md

@@ -0,0 +1,11 @@
+# Import Namespaces
+
+| Namespace                | Description                                                                                                                                                                                                                                                                |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hololinked.core`        | Definition of [`Thing`](thing/index.md) class, [`Property`](property/index.md), [`Action`](action/index.md) and [`Event`](event/index.md) classes, [`StateMachine`](state-machine/state-machine.md), [`Logger`](thing/logger.md) & [`RPCServer`](rpc-server/rpc-server.md) |
+| `hololinked.serializers` | Serializers for different data formats (JSON, MessagePack, etc.) and [`Serializers`](serializers/index.md) singleton.                                                                                                                                                      |
+| `hololinked.server`      | Protocol specific server implementations                                                                                                                                                                                                                                   |
+| `hololinked.client`      | [`ObjectProxy`](clients/object-proxy.md) and protocol specific client implementations, client abstractions and [`ClientFactory`](clients/base.md).                                                                                                                         |
+| `hololinked.param`       | Copy of `param` library with implementation specific modifications.                                                                                                                                                                                                        |
+| `hololinked.storage`     | Database clients for data persistence.                                                                                                                                                                                                                                     |
+| `hololinked.td`          | Thing Description/[ThingModel](td/tm.md) parsing and generation.                                                                                                                                                                                                           |

docs/beginners-guide/code/eventloop/import.py

@@ -9,15 +9,15 @@ This is useful for quick prototyping, or when the action does not require strict
 
 The most expressive way to define payload validation to use type annotations in the action method signature:
 
-```python
+```python linenums="1"
 class Picoscope(Thing):
 
     @action()
-    def run_block(self, 
-            pre_trigger_samples: int, 
-            post_trigger_samples: int, 
+    def run_block(self,
+            pre_trigger_samples: int,
+            post_trigger_samples: int,
             timebase: int,
-            oversample: int = 0, 
+            oversample: int = 0,
             seg_index: int = 0
         ) -> float:
         """Run a single block capture on the Picoscope device"""
@@ -31,73 +31,60 @@ class Picoscope(Thing):
 
 If one generates the Thing Model fragment for the action, the `input` (schema) field will be defined:
 
-```python
+```python linenums="1"
 Picoscope.run_block.to_affordance()
 ```
 
 ```json
 {
-    "run_block": {
-        "title": "run_block",
-        "description": "Run a single block capture on the Picoscope device",
-        "input": {
-            "type": "object",
-            "properties": {
-                "pre_trigger_samples": {
-                    "type": "integer"
-                },
-                "post_trigger_samples": {
-                    "type": "integer"
-                },
-                "timebase": {
-                    "type": "integer"
-                },
-                "oversample": {
-                    "type": "integer",
-                    "default": 0
-                },
-                "seg_index": {
-                    "type": "integer",
-                    "default": 0
-                }
-            },
-            "required": [
-                "pre_trigger_samples",
-                "post_trigger_samples",
-                "timebase"
-            ]
+  "run_block": {
+    "title": "run_block",
+    "description": "Run a single block capture on the Picoscope device",
+    "input": {
+      "type": "object",
+      "properties": {
+        "pre_trigger_samples": {
+          "type": "integer"
         },
-        "output": {
-            "type": "number"
+        "post_trigger_samples": {
+          "type": "integer"
+        },
+        "timebase": {
+          "type": "integer"
+        },
+        "oversample": {
+          "type": "integer",
+          "default": 0
+        },
+        "seg_index": {
+          "type": "integer",
+          "default": 0
         }
+      },
+      "required": ["pre_trigger_samples", "post_trigger_samples", "timebase"]
+    },
+    "output": {
+      "type": "number"
     }
+  }
 }
 ```
 
 This type of validation is made possible by constructing a pydantic model from the type annotations.
 
-For more complex payload validation, one can use JSON schema or pydantic models (directly).
-
-=== "JSON Schema"
-
-    ```python   
-    ```
-
-=== "Pydantic Model"
-
-    ```python
-    ```
+For more complex payload validation, one can use JSON schema or pydantic models (directly). Examples are already included
+in the [handbook](../beginners-guide/articles/actions.md#payload-validation).
 
 The output payload is not validated.
 
 ## Execution Control
 
-Execution control of operations (like `invokeAction`) can be offered in three different ways:
+Execution control of operations (like `invokeaction`) can be offered in three different ways:
 
 - synchronous - queued one after another, default behaviour of **both** properties and actions
     - `Thing` object is not manipulated simultaneously by multiple operations in multiple threads by a remote client, its a fundamental assumption based on the OOP paradigm
-    - prevents incompatible physical actions in the world from running at the same time on the same device
     - maximizes thread safety increasing suitability of runtime for hardware engineers
+    - prevents incompatible physical actions in the world from running at the same time on the same device
 - threaded actions
     - not queued, runs immediately when action is called
     - allows multiple actions to run simultaneously
@@ -113,9 +100,9 @@ flowchart TD
     B -- No --> D[Bind to instance]
     C --> E{Action type}
     D --> E
-    E -- Synchronous --> F[Queue action,<br/>run sequentially]
-    E -- Threaded --> G[Run action in a new thread]
-    E -- Async --> H[Create asyncio task<br/>if requested]
+    E -- synchronous --> F[Queue action,<br/>run sequentially]
+    E -- threaded --> G[Run action in a new thread]
+    E -- asyncio --> H[Create asyncio task]
     F --> I[Validate payload<br/> against the action schema, <br/>Spread payload as arguments]
     G --> J[Validate payload<br/> against the action schema, <br/>Spread payload as arguments]
     H --> K[Validate payload<br/> against the action schema, <br/>Spread payload as arguments]
@@ -126,5 +113,5 @@ flowchart TD
 ```
 
 This scheduling control may need to be implemented in a separate RPC layer or similar. See the [ZMQ RPC layer](zmq.md) for more details.
-
-
+The payload validation step comes after the scheduling decision, as schedulers have higher precedence in the RPC call stack, although
+the logic is common.