Expand documentation

docs/documentation/ForUsers.md

@@ -6,7 +6,7 @@ description: ~
 
 First and foremost, please use a decent IDE. You hearing, Armin?
 
-I tried to shove documentation wherever possible, so that the IDE can give some hints of the type and the meaning of the variables. To do that, just hover your mouse over the thing you want some information. It may not always be helpful, but at least I tried. Also, the code is almost all type annotated, which may also help.
+I tried to shove documentation wherever possible, so that the IDE can give some hints of the type and the meaning of the variables. To do that, just hover your mouse over the thing you want some information. Some IDEs also give autocomplete suggestions, which can be used to the same end. It may not always be helpful, but at least I tried. Also, the code is almost all type annotated, which may also help.
 
 # Package structure
 The installed package contains 4 submodules, that can be divided in two groups, plus a module that will be generated locally. However, normally, you should only need `pyimclsts.network` and the module generated by `pyimclsts.extract`.
@@ -39,8 +39,55 @@ Lastly, when the `pyimclsts.extract` is run with `python3 -m pyimclsts.extract`,
 
 # Publisher-Subscriber model
 
-There are three main elements in this model: a subscriber, a publisher and a message bus. In short, a publisher application writes messages to a shared interface, also known as the message bus, and a subscriber application register with the broker the messages it wants to consume. So, in order to comply with this model, we need a message broker to receive messages from the network, execute the subscribed functions, and also distribute the messages. Additionally, the subscriber functions should be able to have state, run independently (not creating deadlocks nor race conditions), and send and receive messages.
+There are three main elements in this model: a subscriber, a publisher and a message bus. In short, a publisher application writes messages to a shared interface, also known as the message bus, and a subscriber application register with the broker the messages it wants to consume. The message broker, therefore, gathers the messages sent by the publishers and distribute them to the subscribers.
 
 ## The `subscriber`
 
-## The subscriber functions
+In this implementation, the `subscriber` class provides objects that register the subscriber functions. To instantiate it, we give it an interface from which it will read the messages and then we can give it the callbacks for each message we desired. (In a sense, it actually works as a message broker, but we kept this name since from the point of view of the LSTS systems, the applications written with this tools would be subscribers and the vehicles would be the publishers. And I'm lazy and don't want to change it now.)
+
+## The subscriber methods
+
+Besides some private methods (the ones that start with `_`, Python convention), the main subscriber methods are presented below:
+
+```python
+class subscriber:
+    ...
+    def subscribe_async(self, 
+                        callback : Callable[[_core.IMC_message, Callable[[_core.IMC_message], None]], None], 
+                        msg_id : Optional[Union[int, _core.IMC_message, str, _types.ModuleType]] = None, *, 
+                        src : Optional[str] = None, 
+                        src_ent : Optional[str] = None):
+        ...
+
+    def periodic_async(self, 
+                      callback : Callable[[_core.IMC_message], None], 
+                      period : float):
+        ...
+
+    def subscribe_mp(self, 
+                    callback : Callable[[_core.IMC_message, Callable[[_core.IMC_message], None]], None], 
+                    msg_id : Optional[Union[int, _core.IMC_message, str, _types.ModuleType]] = None, *, 
+                    src : Optional[str] = None, 
+                    src_ent : Optional[str] = None):
+        ...
+
+    def call_once(self, 
+                  callback : Callable[[Callable[[_core.IMC_message], None]], None], 
+                  delay : Optional[float] = None) -> None:
+        ...
+
+    def print_information(self) -> None:
+        '''Looks for (and asks for, when applicable) the first Announce and EntityList messages and print them.
+        
+        Executes no other subscription.
+        '''
+        ...
+
+    def stop(self) -> None:
+        ...
+
+    def run(self) -> None:
+        ...
+```
+
+To subscribe a function, there are 3 (+ 1 not yet implemented) possible ways: `subscribe_async`, `periodic_async`, `call_once` and `subscribe_mp` (not implemented). As the names suggest, `call_once` can be used to call a function once, optionally after a delay; `periodic_async` executes a callback every `period` seconds. `subscribe_async` executes the callback for every received message in `msg_id` and filters according to `src` and `src_ent`, if given. `msg_id` can be an `int` (the message id), the message class (or its instance) or a `str` (camel case) or a Python module (the files/modules inside the `category` folder) to specify a category of messages. `src` and `src_ent` are strings that indicate the vehicle and the entity inside a vehicle, for example, "lauv-xplore-1" and "TemperatureSensor".