From: tho <tho@270642c3-0616-0410-b53a-bc976706d245>
Date: Fri, 29 Jan 2010 11:13:46 +0000 (+0000)
Subject: Packets: added documentation about necessary operator<< member for annotations
X-Git-Url: http://g0dil.de/git?a=commitdiff_plain;h=fd884ba2ba992b5032c0644ade77613074216767;p=senf.git

Packets: added documentation about necessary operator<< member for annotations

git-svn-id: https://svn.berlios.de/svnroot/repos/senf/trunk@1556 270642c3-0616-0410-b53a-bc976706d245
---

diff --git a/senf/Packets/Mainpage.dox b/senf/Packets/Mainpage.dox
index 308d9ac..9323740 100644
--- a/senf/Packets/Mainpage.dox
+++ b/senf/Packets/Mainpage.dox
@@ -676,6 +676,10 @@
     struct Timestamp {
         senf::ClockService::clock_t value;
     };
+    
+    std::ostream & operator<<(std::ostream & os, Timestamp const & tstamp) { 
+        os << tstamp.value; return os; 
+    }
 
     senf::EthernetPacket packet (senf::EthernetPacket::create(senf::noinit));
     sock.read(packet.data(), 0u);
@@ -687,17 +691,20 @@
     \code
     if (senf::ClockService::now() - packet.annotation<Timestamp>().value 
             > senf::ClockService::seconds(1)) {
-        // Ouch ... this packet is to old
+        // this packet is to old
         // ...
     }
     \endcode
-
+    
     It is very important to define a specific structure (or class or enum) type for each type of
     annotation. \e Never directly store a fundamental type as an annotation: The name of the type is
     used to look up the annotation, so you can store only one annotation for each built-in type. \c
     typedef does not help since \c typedef does not introduce new type names, it only defines an
     alias.
 
+    The annotation type must support the output \c operator<< for description purposes 
+    (e.g. for the \ref senf::Packet::dump() "Packet::dump()" member). 
+
     Of course, the annotation structure can be arbitrary. However, one very important caveat: If the
     annotation is not a POD type, it needs to inherit from senf::ComplexAnnotation. A type is POD,
     if it is really just a bunch of bytes: No (non-static) members, no constructor or destructor and