diff --git a/reaction.yml b/reaction.yml
index 754c557..d953817 100644
--- a/reaction.yml
+++ b/reaction.yml
@@ -1,26 +1,44 @@
 ---
 # TODO heavily comment this file
+# definitions are just a place to put chunks of conf you want to reuse in another place
+# they're not readed by reaction
 definitions:
   - &iptablesban [ "iptables" "-w" "-I" "reaction" "1" "-s" "<ip>" "-j" "block" ]
   - &iptablesunban [ "iptables" "-w" "-D" "reaction" "1" "-s" "<ip>" "-j" "block" ]
 
+# patterns are substitued in regexes.
+# when a filter performs an action, it replaces the found pattern
 patterns:
   ip: '(([0-9]{1,3}\.){3}[0-9]{1,3})|([0-9a-fA-F:]{2,90})'
 
+# streams are command that are run
+# their output will be used by one or more filters
 streams:
+  # streams have a user-defined name
   ssh:
     # note that if the command is not in environment's `PATH`
     # its full path must be given.
     cmd: [ "journalctl" "-fu" "sshd.service" ]
+    # filters are a set of regexes on a stream
+    # when a regex matches, it will trigger the filter's actions
     filters:
+      # filters have a user-defined name
       failedlogin:
         regex:
           - authentication failure;.*rhost=<ip>
+        # if retry and retry-period are defined,
+        # the actions will only take place if a same pattern is
+        # found `retry` times in a `retry-period` interval
         retry: 3
+        # format is defined here: https://pkg.go.dev/time#ParseDuration
         retry-period: 6h
         actions:
+          # actions have a user-defined name
           ban:
+            # YAML substitutes *reference by the value at &reference
             cmd: *iptablesban
           unban:
             cmd:  *iptablesunban
+            # if after is defined, the action will not take place immediately, but after a specified duration.
+            # same format as retry-period
             after: 2d