Developer documentation at Readme.org.

README.org

@@ -1,6 +1,7 @@
 #+TITLE: jabber.el
 #+SUBTITLE: XMPP client for Emacs
 #+DESCRIPTION: Documentation
+#+startup: inlineimages
 
 * Explanation
 :PROPERTIES:
@@ -210,6 +211,98 @@ To install the Info documentation, copy =jabber.info= to =/usr/local/info= and r
 6. Address the issues presented by the linters and tests. Hitting Enter on an error in the compilation buffer will take you to the source in =jabber.el= - use =org-babel-tangle-jump-to-org= to go to the source block in =jabber.org=.
 7. Push and create your PR, or send a patch using [[https://git-send-email.io/][=git-send-email=]] to wgreenhouse@tilde.club
 
+* Developer documentation
+
+** Required Libraries Summary 
+This documentation is more understandable if the reader know their purpose in advance. For this reason, this section provides a summary about them. Please, refer to their own Website or documentation manual for extensive documentation. Some interesting tips are provided to ease the debugging process and further developing of the jabber library.
+  
+*** fsm
+The Finite State Machine library implements functions to define multiple finite state machines (FSM), their states and all the events associated to each of them.
+
+The following is a list of the most important functions or macros defined in this library:
+
+- ~(define-state-machine name &key start sleep)~
+- ~(define-state fsm-name state-name arglist &body body)~
+- ~(define-enter-state fsm-name state-name arglist &body body)~
+- ~(define-fsm name &key strat sleep states ...)~
+- ~(fsm-send fsm event &optional callback)~
+- ~(fsm-call fsm event)~
+
+It is required a name and the starting state to define a new FSM. The ~define-state-machine~ creates a new function called ~start-NAME~. Its ~start~ argument is a function argument and body definition used by the created function. The result of the new function must be a list ~(STATE STATE-DATA [TIMEOUT])~ which is the starting state of the machine.
+
+See [[file:jabber.org::*jabber-connection][jabber-connection]] section for an example. Its ~:start~ parameter explicitly mentioned, and its value is a list with the arguments ( ~(username server resource ...)~ ), a docstring ( ~"Start a jabber connection."~ ) and the body of the ~start-jabber-connection~ function.
+
+The machine requires states. They are defined with the ~define-state~ function.
+
+** Debugging Tips
+Useful tips for debugging:
+
+- There is a buffer called ~*fsm-debug*~ that displays all transitions and errors during the event handling. 
+- There is a jabber-debug customization group.
+- You can set ~jabber-debug-log-xml~ variable to ~t~ to enable the XML debug console. See [[file:jabber.org::#debug-log-xml][Section debug-log-xml at jabber.org]].
+- The XML console is a buffer called ~*-jabber-console-ACCOUNT-*~ by default. Enable ~jabber-debug-log-xml~ and switch to that buffer to see the incoming and outgoing XML stanzas. See [[file:jabber.org::#xml-console-mode][Section xml-console-mode at jabber.org]].
+
+** The jabber-connection FSM
+The jabber.el use a finite state machine (FSM) to track the current jabber connection step. It defines a FSM called ~jabber-connection~ (or ~jc~ when it is used as parameter in functions) and several states along with their sentinels. See [[file:jabber.org::#connection][Section jabber-connection at jabber.org]] where it is defined. The Org-mode tag ~:fsm:~ is used at jabber.org headlines to describe FSM definitions.
+
+*** States
+The following graph shows the states and their transition implemented in version [[https://tildegit.org/wgreenhouse/emacs-jabber/commit/dddcccb926f422b03d22a66b60db46f1266eb141][dddcccb926]] (20 march 2021). The nodes represents the states and the arc are events.
+
+All states have filter and sentinel events that do not change the FSM state. Also, they have a ~:do-disconnect~ event that change the FSM to the ~nil~ state except for the ~connecting~ state.
+
+Some state changes depend on the event and the data received, in this case, the event name has a number added. For instance, ~:stream-start1~, ~:stream-start2~ and ~:stream-start3~ is the same event (~:stream-start~) but triggers different states changes depending on the data received.
+
+#+name: fig:states
+#+BEGIN_SRC dot :file images/states-dot.png :exports results :tangle no
+  digraph "jabber-connection" {
+          nil;
+
+          connecting -> connected [label=":connected"];
+          connecting -> nil [label=":connection-failed"];
+          connecting -> defer [label=":do-disconnect"];
+
+          connected -> "connected" [label=":filter, :sentinel, :stream-start1,"];
+          connected -> "register-account" [label=":stream-start2, :stanza1"];
+          connected -> "legacy-auth" [label=":stream-start3"];
+          connected -> "starttls" [label=":stanza2"];
+          connected -> "sasl-auth" [label=":stanza3"];
+
+          "register-account" -> "register-account" [label=":stanza"];
+
+          starttls -> connected [label=":stanza"];
+
+          "legacy-auth" -> "legacy-auth" [label=":stanza"];
+          "legacy-auth" -> "session-established" [label=":authontication-success"];
+          "legacy-auth" -> "nil" [label=":authentication-failure"];
+
+          "sasl-auth" -> "sasl-auth" [label=":stanza"];
+          "sasl-auth" -> "legacy-auth" [label=":use-legacy-auth-instead"];
+          "sasl-auth" -> bind [label=":authentication-success"];
+          "sasl-auth" -> nil [label=":authentication-failure"];
+
+          bind -> bind [label=":stream-start, :stanza1"];
+          bind -> nil [label=":stanza2, :bind-failure, :session-failure"];
+          bind -> "session-established" [label=":bind-success, :session-success"];
+
+          "session-established" -> "session-established" [label=":stanza; :roster-update, :timeout, :send-if-connected"];
+  }
+#+END_SRC
+
+#+caption: Implemented states in the Jabber FSM.
+#+RESULTS: fig:states
+[[file:images/states-dot.png]]
+
+
+** How is the Stanza processing
+The following is a brief summary about the stanza processing.
+
+1. The ~:session-established~ state is reached.
+2. The FSM receives the event ~:stanza~ at the ~:session-established~ state.
+3. If no error has been found, call ~jabber-process-input~. See [[file:jabber.org::*jabber-process-input][jabber-process-input]] section.
+4. Select one of the following variables depending on the type of message received: ~jabber-iq-chain~, ~jabber-presence-chain~ and ~jabber-message-chain~. All of them contains a list of functions that process its type of message.
+5. Call all of their functions with the jabber connection and XML data as parameters .
+6. Continue in the same state.
+
 * TODO maintenance [0%]
 :PROPERTIES:
 :CUSTOM_ID: maintenance