--- a/src/internet/model/ipv6-raw-socket-factory.h	Sun Dec 18 21:30:46 2011 -0800
+++ b/src/internet/model/ipv6-raw-socket-factory.h	Tue Dec 20 18:57:31 2011 +0100
@@ -35,6 +35,29 @@
  *
  * This abstract class defines the API for IPv6 RAW socket factory.
  * 
+ * A RAW Socket typically is used to access specific IP layers not usually
+ * available through L4 sockets, e.g., ICMP. The implementer should take
+ * particular care to define the Ipv6RawSocketImpl Attributes, and in
+ * particular the Protocol attribute.
+ * Not setting it will result in a zero protocol at IP level (corresponding
+ * to the HopByHop IPv6 Extension header, i.e., Ipv6ExtensionHopByHopHeader)
+ * when sending data through the socket, which is probably not the intended
+ * behavior.
+ *
+ * A correct example is (from src/applications/model/radvd.cc):
+ * \code
+   if (!m_socket)
+     {
+       TypeId tid = TypeId::LookupByName ("ns3::Ipv6RawSocketFactory");
+       m_socket = Socket::CreateSocket (GetNode (), tid);
+
+       NS_ASSERT (m_socket);
+
+       m_socket->SetAttribute ("Protocol", UintegerValue(Ipv6Header::IPV6_ICMPV6));
+       m_socket->SetRecvCallback (MakeCallback (&Radvd::HandleRead, this));
+     }
+ * \endcode
+ *
  */
 class Ipv6RawSocketFactory : public SocketFactory
 {

--- a/src/internet/model/ipv6-raw-socket-impl.h	Sun Dec 18 21:30:46 2011 -0800
+++ b/src/internet/model/ipv6-raw-socket-impl.h	Tue Dec 20 18:57:31 2011 +0100
@@ -36,6 +36,30 @@
 /**
  * \class Ipv6RawSocketImpl
  * \brief IPv6 raw socket.
+ *
+ * A RAW Socket typically is used to access specific IP layers not usually
+ * available through L4 sockets, e.g., ICMP. The implementer should take
+ * particular care to define the Ipv6RawSocketImpl Attributes, and in
+ * particular the Protocol attribute.
+ * Not setting it will result in a zero protocol at IP level (corresponding
+ * to the HopByHop IPv6 Extension header, i.e., Ipv6ExtensionHopByHopHeader)
+ * when sending data through the socket, which is probably not the intended
+ * behavior.
+ *
+ * A correct example is (from src/applications/model/radvd.cc):
+ * \code
+   if (!m_socket)
+     {
+       TypeId tid = TypeId::LookupByName ("ns3::Ipv6RawSocketFactory");
+       m_socket = Socket::CreateSocket (GetNode (), tid);
+
+       NS_ASSERT (m_socket);
+
+       m_socket->SetAttribute ("Protocol", UintegerValue(Ipv6Header::IPV6_ICMPV6));
+       m_socket->SetRecvCallback (MakeCallback (&Radvd::HandleRead, this));
+     }
+ * \endcode
+ *
  */
 class Ipv6RawSocketImpl : public Socket
 {