diff --git a/src/detect.h b/src/detect.h
index 4fa884f292..97f0bbf929 100644
--- a/src/detect.h
+++ b/src/detect.h
@@ -22,47 +22,81 @@
 struct SCSigOrderFunc_;
 struct SCSigSignatureWrapper_;
 
+/*
+
+  The detection engine groups similar signatures/rules together. Internally a
+  tree of different types of data is created on initialization. This is it's
+  global layout:
+
+   For TCP/UDP
+
+   Packet data size (dsize)
+   - Flow direction
+   -- Protocol
+   -=- Src address
+   -==- Dst address
+   -===- Src port
+   -====- Dst port
+
+   For the other protocols
+
+   Packet data size (dsize)
+   - Flow direction
+   -- Protocol
+   -=- Src address
+   -==- Dst address
+
+*/
+
 /*
  * DETECT ADDRESS
  */
 
 /* a is ... than b */
 enum {
-    ADDRESS_ER = -1, /* error e.g. compare ipv4 and ipv6 */
-    ADDRESS_LT,      /* smaller              [aaa] [bbb] */
-    ADDRESS_LE,      /* smaller with overlap [aa[bab]bb] */
-    ADDRESS_EQ,      /* exactly equal        [abababab]  */
-    ADDRESS_ES,      /* within               [bb[aaa]bb] and [[abab]bbb] and [bbb[abab]] */
-    ADDRESS_EB,      /* completely overlaps  [aa[bbb]aa] and [[baba]aaa] and [aaa[baba]] */
-    ADDRESS_GE,      /* bigger with overlap  [bb[aba]aa] */
-    ADDRESS_GT,      /* bigger               [bbb] [aaa] */
+    ADDRESS_ER = -1, /**< error e.g. compare ipv4 and ipv6 */
+    ADDRESS_LT,      /**< smaller              [aaa] [bbb] */
+    ADDRESS_LE,      /**< smaller with overlap [aa[bab]bb] */
+    ADDRESS_EQ,      /**< exactly equal        [abababab]  */
+    ADDRESS_ES,      /**< within               [bb[aaa]bb] and [[abab]bbb] and [bbb[abab]] */
+    ADDRESS_EB,      /**< completely overlaps  [aa[bbb]aa] and [[baba]aaa] and [aaa[baba]] */
+    ADDRESS_GE,      /**< bigger with overlap  [bb[aba]aa] */
+    ADDRESS_GT,      /**< bigger               [bbb] [aaa] */
 };
 
-#define ADDRESS_FLAG_ANY            0x01
-#define ADDRESS_FLAG_NOT            0x02
+#define ADDRESS_FLAG_ANY            0x01 /**< address is "any" */
+#define ADDRESS_FLAG_NOT            0x02 /**< address is negated */
 
-#define ADDRESS_SIGGROUPHEAD_COPY   0x04
-#define ADDRESS_PORTS_COPY          0x08
+#define ADDRESS_SIGGROUPHEAD_COPY   0x04 /**< sgh is a ptr to another sgh */
+#define ADDRESS_PORTS_COPY          0x08 /**< ports are a ptr to other ports */
 #define ADDRESS_PORTS_NOTUNIQ       0x10
-#define ADDRESS_HAVEPORT            0x20
+#define ADDRESS_HAVEPORT            0x20 /**< address has a ports ptr */
 
+/** \brief address structure for use in the detection engine.
+ *
+ *  Contains the address information and matching information.
+ */
 typedef struct DetectAddress_ {
-    /* address data for this group */
-    uint8_t family;
-    uint32_t ip[4];
-    uint32_t ip2[4];
+    /** address data for this group */
+    uint8_t family; /**< address family, AF_INET (IPv4) or AF_INET6 (IPv6) */
+    uint32_t ip[4]; /**< the address, or lower end of a range */
+    uint32_t ip2[4]; /**< higher end of a range */
 
-    /* XXX ptr to rules, or PortGroup or whatever */
+    /** ptr to the next address (dst addr in that case) or to the src port */
     union {
-        struct DetectAddressHead_ *dst_gh;
-        struct DetectPort_ *port;
+        struct DetectAddressHead_ *dst_gh; /**< destination address */
+        struct DetectPort_ *port; /**< source port */
     };
-    /* signatures that belong in this group */
+
+    /** signatures that belong in this group */
     struct SigGroupHead_ *sh;
+
+    /** flags affecting this address */
     uint8_t flags;
 
-    /* double linked list */
+    /** ptr to the previous address in the list */
     struct DetectAddress_ *prev;
+    /** ptr to the next address in the list */
     struct DetectAddress_ *next;
 
     uint32_t cnt;
diff --git a/src/flow-private.h b/src/flow-private.h
index 826ede7dae..4aaafa303f 100644
--- a/src/flow-private.h
+++ b/src/flow-private.h
@@ -7,20 +7,38 @@
 #include "flow-queue.h"
 
 /* per flow flags */
+
+/** At least on packet from the source address was seen */
 #define FLOW_TO_SRC_SEEN            0x0001
+/** At least on packet from the destination address was seen */
 #define FLOW_TO_DST_SEEN            0x0002
 
+/** Flow lives in the flow-state-NEW list */
 #define FLOW_NEW_LIST               0x0004
+/** Flow lives in the flow-state-EST (established) list */
 #define FLOW_EST_LIST               0x0008
+/** Flow lives in the flow-state-CLOSED list */
 #define FLOW_CLOSED_LIST            0x0010
 
+/** Flow was inspected against IP-Only sigs in the toserver direction */
 #define FLOW_TOSERVER_IPONLY_SET    0x0020
+/** Flow was inspected against IP-Only sigs in the toclient direction */
 #define FLOW_TOCLIENT_IPONLY_SET    0x0040
 
-#define FLOW_NOPACKET_INSPECTION    0x0080  /**< Flag to indicate the packet belongs to this flow should not be inspected*/
-#define FLOW_NOPAYLOAD_INSPECTION   0x0100  /**< Flag to indicate the contents or the packet which belongs to this flow should not be inspected*/
+/** Packet belonging to this flow should not be inspected at all */
+#define FLOW_NOPACKET_INSPECTION    0x0080
+/** Packet payloads belonging to this flow should not be inspected */
+#define FLOW_NOPAYLOAD_INSPECTION   0x0100
+
+/** All packets in this flow should be dropped */
+#define FLOW_ACTION_DROP            0x0200
+
 
 /* global flow flags */
+
+/** Flow engine is in emergency mode. This means it doesn't have enough spare
+ *  flows for new flows and/or it's memcap limit it reached. In this state the
+ *  flow engine with evaluate flows with lower timeout settings. */
 #define FLOW_EMERGENCY   0x01
 
 /* Flow Time out values */
diff --git a/src/flow.h b/src/flow.h
index 842e8d71e9..a420fbbcb2 100644
--- a/src/flow.h
+++ b/src/flow.h
@@ -19,8 +19,6 @@
 #define FLOW_PKT_NOSTREAM               0x40
 #define FLOW_PKT_STREAMONLY             0x80
 
-#define FLOW_ACTION_DROP                0x100
-
 /* global flow config */
 typedef struct FlowCnf_
 {