From acf10525f65e814b01073d97c26d3ab76934a39d Mon Sep 17 00:00:00 2001
From: Eric Leblond <eric@regit.org>
Date: Wed, 26 Oct 2011 18:00:44 +0200
Subject: [PATCH] doc: add decode group and related documentation.

---
 src/decode-ethernet.c | 10 ++++++++++
 src/decode-gre.c      | 10 ++++++++++
 src/decode-icmpv4.c   | 10 ++++++++++
 src/decode-icmpv6.c   | 10 ++++++++++
 src/decode-ipv4.c     | 10 ++++++++++
 src/decode-ipv6.c     | 10 ++++++++++
 src/decode-ppp.c      | 10 ++++++++++
 src/decode-pppoe.c    | 10 ++++++++++
 src/decode-raw.c      | 10 ++++++++++
 src/decode-sctp.c     | 10 ++++++++++
 src/decode-sll.c      | 10 ++++++++++
 src/decode-tcp.c      | 10 ++++++++++
 src/decode-udp.c      | 10 ++++++++++
 src/decode-vlan.c     | 10 ++++++++++
 src/decode.c          | 27 +++++++++++++++++++++++++++
 src/suricata.h        |  1 +
 16 files changed, 168 insertions(+)

diff --git a/src/decode-ethernet.c b/src/decode-ethernet.c
index bf7d7718ad..3a257f52da 100644
--- a/src/decode-ethernet.c
+++ b/src/decode-ethernet.c
@@ -15,6 +15,13 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \ingroup decode
+ *
+ * @{
+ */
+
+
 /**
  * \file
  *
@@ -133,3 +140,6 @@ void DecodeEthernetRegisterTests(void) {
     UtRegisterTest("DecodeEthernetTest01", DecodeEthernetTest01, 0);
 #endif /* UNITTESTS */
 }
+/**
+ * @}
+ */
diff --git a/src/decode-gre.c b/src/decode-gre.c
index 4b87c45016..de5043494c 100644
--- a/src/decode-gre.c
+++ b/src/decode-gre.c
@@ -15,6 +15,13 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \ingroup decode
+ *
+ * @{
+ */
+
+
 /**
  * \file
  *
@@ -385,3 +392,6 @@ void DecodeGRERegisterTests(void) {
     UtRegisterTest("DecodeGREtest03", DecodeGREtest03, 1);
 #endif /* UNITTESTS */
 }
+/**
+ * @}
+ */
diff --git a/src/decode-icmpv4.c b/src/decode-icmpv4.c
index d96ec23427..725b567ab9 100644
--- a/src/decode-icmpv4.c
+++ b/src/decode-icmpv4.c
@@ -15,6 +15,13 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \ingroup decode
+ *
+ * @{
+ */
+
+
 /**
  * \file
  *
@@ -769,3 +776,6 @@ void DecodeICMPV4RegisterTests(void) {
     UtRegisterTest("DecodeICMPV4test08", DecodeICMPV4test08, 1);
 #endif /* UNITTESTS */
 }
+/**
+ * @}
+ */
diff --git a/src/decode-icmpv6.c b/src/decode-icmpv6.c
index b199b519ef..918b912326 100644
--- a/src/decode-icmpv6.c
+++ b/src/decode-icmpv6.c
@@ -15,6 +15,13 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \ingroup decode
+ *
+ * @{
+ */
+
+
 /**
  * \file
  *
@@ -1106,3 +1113,6 @@ void DecodeICMPV6RegisterTests(void)
     UtRegisterTest("ICMPV6PayloadTest01", ICMPV6PayloadTest01, 1);
 #endif /* UNITTESTS */
 }
+/**
+ * @}
+ */
diff --git a/src/decode-ipv4.c b/src/decode-ipv4.c
index 2ef62b7c84..d072058b40 100644
--- a/src/decode-ipv4.c
+++ b/src/decode-ipv4.c
@@ -15,6 +15,13 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \ingroup decode
+ *
+ * @{
+ */
+
+
 /**
  * \file
  *
@@ -1955,3 +1962,6 @@ void DecodeIPV4RegisterTests(void) {
     UtRegisterTest("DecodeIPV4DefragTest03", DecodeIPV4DefragTest03, 1);
 #endif /* UNITTESTS */
 }
+/**
+ * @}
+ */
diff --git a/src/decode-ipv6.c b/src/decode-ipv6.c
index 3785ace74f..681a7e1688 100644
--- a/src/decode-ipv6.c
+++ b/src/decode-ipv6.c
@@ -15,6 +15,13 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \ingroup decode
+ *
+ * @{
+ */
+
+
 /**
  * \file
  *
@@ -498,3 +505,6 @@ void DecodeIPV6(ThreadVars *tv, DecodeThreadVars *dtv, Packet *p, uint8_t *pkt,
     return;
 }
 
+/**
+ * @}
+ */
diff --git a/src/decode-ppp.c b/src/decode-ppp.c
index ea0cabd5bd..8085603e8b 100644
--- a/src/decode-ppp.c
+++ b/src/decode-ppp.c
@@ -15,6 +15,13 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \ingroup decode
+ *
+ * @{
+ */
+
+
 /**
  * \file
  *
@@ -303,3 +310,6 @@ void DecodePPPRegisterTests(void) {
 #endif /* UNITTESTS */
 }
 
+/**
+ * @}
+ */
diff --git a/src/decode-pppoe.c b/src/decode-pppoe.c
index e0a0acce15..f06e4d71dd 100644
--- a/src/decode-pppoe.c
+++ b/src/decode-pppoe.c
@@ -15,6 +15,13 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \ingroup decode
+ *
+ * @{
+ */
+
+
 /**
  * \file
  *
@@ -449,3 +456,6 @@ void DecodePPPOERegisterTests(void) {
 #endif /* UNITTESTS */
 }
 
+/**
+ * @}
+ */
diff --git a/src/decode-raw.c b/src/decode-raw.c
index 200509f410..97c479fe68 100644
--- a/src/decode-raw.c
+++ b/src/decode-raw.c
@@ -15,6 +15,13 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \ingroup decode
+ *
+ * @{
+ */
+
+
 /**
  * \file
  *
@@ -212,3 +219,6 @@ void DecodeRawRegisterTests(void) {
     UtRegisterTest("DecodeRawTest03", DecodeRawTest03, 0);
 #endif /* UNITTESTS */
 }
+/**
+ * @}
+ */
diff --git a/src/decode-sctp.c b/src/decode-sctp.c
index d83831e86c..24d83e409f 100644
--- a/src/decode-sctp.c
+++ b/src/decode-sctp.c
@@ -15,6 +15,13 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \ingroup decode
+ *
+ * @{
+ */
+
+
 /**
  * \file
  *
@@ -71,3 +78,6 @@ void DecodeSCTP(ThreadVars *tv, DecodeThreadVars *dtv, Packet *p, uint8_t *pkt,
 
     return;
 }
+/**
+ * @}
+ */
diff --git a/src/decode-sll.c b/src/decode-sll.c
index 82dd697cf2..4c1dff3e6a 100644
--- a/src/decode-sll.c
+++ b/src/decode-sll.c
@@ -15,6 +15,13 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \ingroup decode
+ *
+ * @{
+ */
+
+
 /**
  * \file
  *
@@ -62,3 +69,6 @@ void DecodeSll(ThreadVars *tv, DecodeThreadVars *dtv, Packet *p, uint8_t *pkt, u
                        pkt, ntohs(sllh->sll_protocol));
     }
 }
+/**
+ * @}
+ */
diff --git a/src/decode-tcp.c b/src/decode-tcp.c
index 274d0270a3..9e2b07c08b 100644
--- a/src/decode-tcp.c
+++ b/src/decode-tcp.c
@@ -15,6 +15,13 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \ingroup decode
+ *
+ * @{
+ */
+
+
 /**
  * \file
  *
@@ -510,3 +517,6 @@ void DecodeTCPRegisterTests(void)
     UtRegisterTest("TCPGetSackTest01", TCPGetSackTest01, 1);
 #endif /* UNITTESTS */
 }
+/**
+ * @}
+ */
diff --git a/src/decode-udp.c b/src/decode-udp.c
index 8e669758a7..f9483d8126 100644
--- a/src/decode-udp.c
+++ b/src/decode-udp.c
@@ -15,6 +15,13 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \ingroup decode
+ *
+ * @{
+ */
+
+
 /**
  * \file
  *
@@ -198,3 +205,6 @@ void DecodeUDPV4RegisterTests(void)
                    UDPV6CalculateInvalidChecksumtest04, 0);
 #endif /* UNITTESTS */
 }
+/**
+ * @}
+ */
diff --git a/src/decode-vlan.c b/src/decode-vlan.c
index c860f3465b..4c1841e012 100644
--- a/src/decode-vlan.c
+++ b/src/decode-vlan.c
@@ -15,6 +15,13 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \ingroup decode
+ *
+ * @{
+ */
+
+
 /**
  * \file
  *
@@ -224,3 +231,6 @@ void DecodeVLANRegisterTests(void) {
 #endif /* UNITTESTS */
 }
 
+/**
+ * @}
+ */
diff --git a/src/decode.c b/src/decode.c
index b35ebe7db8..ec0c1ee9a4 100644
--- a/src/decode.c
+++ b/src/decode.c
@@ -15,6 +15,30 @@
  * 02110-1301, USA.
  */
 
+/**
+ * \defgroup decode Packet decoding
+ *
+ * \brief Code in charge of protocol decoding
+ *
+ * The task of decoding packets is made in different files and
+ * as Suricata is supporting encapsulation there is a potential
+ * recursivity in the call.
+ *
+ * For each protocol a DecodePROTO function is provided. For
+ * example we have DecodeIPV4() for IPv4 and DecodePPP() for
+ * PPP.
+ *
+ * These functions have all a pkt and and a len argument which
+ * are respectively a pointer to the protocol data and the length
+ * of this protocol data.
+ *
+ * \attention The pkt parameter must point to the effective data because
+ * it will be used later to set per protocol pointer like Packet::tcph
+ *
+ * @{
+ */
+
+
 /**
  * \file
  *
@@ -321,3 +345,6 @@ inline int PacketCopyData(Packet *p, uint8_t *pktdata, int pktlen)
     SET_PKT_LEN(p, (size_t)pktlen);
     return PacketCopyDataOffset(p, 0, pktdata, pktlen);
 }
+/**
+ * @}
+ */
diff --git a/src/suricata.h b/src/suricata.h
index ccddc651bb..3a9974c563 100644
--- a/src/suricata.h
+++ b/src/suricata.h
@@ -34,6 +34,7 @@
  *
  * Documentation is generate from comments placed in all parts of the code.
  * But you will also find some groups describing specific functional parts:
+ *  - \ref decode
  *  - \ref httplayer
  *  - \ref sigstate
  *  - \ref threshold