Documentation updates

PPI/Mainpage.dox

@@ -78,8 +78,9 @@
     \section ppi_packets Packets
 
     The PPI processes packets and uses the <a href="@TOPDIR@/Packets/doc/html/index.html">Packet
-    library</a> to handle them. All packets are passed around as generic \ref senf::Packet
-    references, the PPI does not enforce any packet type restrictions.
+    library</a> to handle them. All packets are internally passed around as generic \ref
+    senf::Packet references, however connectors may optionally be defined as sending or receiving
+    packets of a specific type only.
 
     \section ppi_modules Modules
 
@@ -212,6 +213,9 @@
     To provide this flexibility, all input connectors incorporate a packet queue. This queue is
     exposed to the module and allows the module to optionally process packets in batches.
 
+    Connectors take an optional template argument which allows to specify the type of packet this
+    connector sends or received. This template arguments defaults to \ref senf::Packet.
+
     \see \ref senf::ppi::connector
 
     \section ppi_connections Connections

Packets/Mainpage.dox

@@ -105,19 +105,20 @@
     eth.next().is<IPv4Packet>();        // true
     eth.next().next() == udp;           // true
     eth.next().is<UDPPacket>();         // false
-    eth.next<UDPPacket>() == udp;       // true
+    eth.find<UDPPacket>() == udp;       // true
 
-    udp.next<UDPPacket>();              // throws InvalidPacketChainException
-    udp.next<UDPPacket>(senf::nothrow); // a senf::Packet testing as false
-    udp.findNext<UDPPacket()> == udp;   // true
-    udp.first<IPv4Packet>() == ip;      // true
+    udp.find<EthernetPacket>();         // throws InvalidPacketChainException
+    udp.find<EthernetPacket>(senf::nothrow); // An in-valid senf::Packet which tests as 'false'
+    udp.find<UDPPacket()> == udp;       // true
+    udp.first<IPv4Packet>();            // throws InvalidPacketChainException
 
     udp.prev() == ip;                   // true
-    udp.prev<EthernetPacket>() == eth   // true
+    udp.prev<EthernetPacket>();         // throws Inv
     \endcode
 
-    ... and so on. It is therefore not necessary to stash away a reference for every interpreter (as
-    each of the sub-packets are called) as long as at least one reference is available.
+    ... and so on. See the senf::Packet documentation for more. Using these members, the complete
+    chain of packet interpreters (as these sub-packets or headers are called) may be traversed from
+    any packet handle.
 
     These chain navigation functions are also used to parse a packet. Let's read an Ethernet packet
     from a packet socket handle:
@@ -133,17 +134,20 @@
 
     \code
     try {
-        senf::UDPPacket udp (packet.findNext<UDPPacket>(senf::nothrow));
-        if (udp && udp->destination() == 2001u) {
+        senf::UDPPacket udp (packet.find<UDPPacket>());
+        if (udp->destination() == 2001u) {
             // Voila ...
         }
-    } catch (senf::TruncatedPacketException const &) {
-        std::cerr << "Ooops !! Broken packet received ...\n"
+    } catch (senf::TruncatedPacketException &) {
+        std::cerr << "Ooops !! Broken packet received\n";
+    } catch (senf::InvalidPacketChainException &) {
+        std::cerr << "Not a udp packet\n";
     }
     \endcode
 
     TruncatedPacketException is thrown by <tt>udp->destination()</tt> if that field cannot be
-    accessed. More generally, whenever a field cannot be accessed because it would be out of bounds
+    accessed (that is it would be beyond the data read which means we have read a truncated
+    packet). More generally, whenever a field cannot be accessed because it would be out of bounds
     of the data read, this exception is generated.
 
     This is only a very short introduction to the library to give a feel for the implementation. For

Socket/Protocols/BSDSocketProtocol.hh

@@ -92,18 +92,22 @@ namespace senf {
                                              \param[in] v new socket priority */
 
         unsigned rcvbuf() const;        ///< Check receive buffer size
-                                        /**< \param[in] handle socket handle to check
-                                             \returns size of receive buffer in bytes */
+                                        /**< \returns size of receive buffer in bytes 
+                                             \internal Linux doubles the buffer size internally when
+                                                 changing it to cater for additional space needed by
+                                                 the linux kernel. This call will therefore return
+                                                 only half the value reported by the kernel. */
         void rcvbuf(unsigned size) const; ///< Change receive buffer size
-                                        /**< \param[in] handle socket handle
-                                             \param[in] size new receive buffer size */
+                                        /**< \param[in] size new receive buffer size */
 
         unsigned sndbuf() const;        ///< Check send buffer size
-                                        /**< \param[in] handle socket handle to check
-                                             \returns size of send buffer in bytes */
+                                        /**< \returns size of send buffer in bytes 
+                                             \internal Linux doubles the buffer size internally when
+                                                 changing it to cater for additional space needed by
+                                                 the linux kernel. This call will therefore return
+                                                 only half the value reported by the kernel. */
         void sndbuf(unsigned size) const; ///< Change size of send buffer
-                                        /**< \param[in] handle socket handle
-                                             \param[in] size new send buffer size */
+                                        /**< \param[in] size new send buffer size */
         
     };