Merge pull request #199 from jougs/master

improved documentation

nestkernel/connector_model.h

@@ -37,14 +37,27 @@ class CommonSynapseProperties;
 class TimeConverter;
 class Node;
 
-
+/**
+ * This function sets the two lowest bits of the pointer depending on the existing connections.
+ *
+ * - If *p contains primary connections the lowest bit is set to 1
+ * - If *p contains secondary connections the second lowest bit is set to 1
+ *
+ * This implementation relies on the assumption that the two lowest bits of the pointer are 0.
+ * This can be assumed with some certainty (see github issue #186 for a discussion).
+ * The assumption is secured by an assert in the allocate()-function.
+ */
 inline ConnectorBase*
 pack_pointer( ConnectorBase* p, bool has_primary, bool has_secondary )
 {
   return reinterpret_cast< ConnectorBase* >(
     reinterpret_cast< unsigned long >( p ) | has_primary | ( has_secondary << 1 ) );
 }
 
+/**
+ * This function removes the setting of the two lowest bits done in the pack_pointer()-function.
+ * The returned pointer can again be used as a valid pointer.
+ */
 inline ConnectorBase*
 validate_pointer( ConnectorBase* p )
 {
@@ -56,16 +69,14 @@ validate_pointer( ConnectorBase* p )
 inline bool
 has_primary( ConnectorBase* p )
 {
-  // the lowest bit is set, if there is at least one primary
-  // connection
+  // the lowest bit is set, if there is at least one primary connection
   return static_cast< bool >( reinterpret_cast< unsigned long >( p ) & 1 );
 }
 
 inline bool
 has_secondary( ConnectorBase* p )
 {
-  // the second lowest bit is set, if there is at least one secondary
-  // connection
+  // the second lowest bit is set, if there is at least one secondary connection
   return static_cast< bool >( reinterpret_cast< unsigned long >( p ) & 2 );
 }
 

nestkernel/connector_model_impl.h

@@ -388,6 +388,10 @@ GenericConnectorModel< ConnectionT >::add_connection( Node& src,
   {
     // case 1 or case 2
 
+    // Already existing pointers of type ConnectorBase contain (in their two lowest bits) the
+    // information if *conn has primary and/or secondary connections. Before the pointer can
+    // be used as a valid pointer this information needs to be read and the original pointer
+    // needs to be restored by calling validate_pointer( conn ).
     bool b_has_primary = has_primary( conn );
     bool b_has_secondary = has_secondary( conn );
 
@@ -405,8 +409,7 @@ GenericConnectorModel< ConnectionT >::add_connection( Node& src,
         vector_like< ConnectionT >* vc = static_cast< vector_like< ConnectionT >* >( conn );
 
         // we do not need to change the flags is_primary or is_secondary, because the new synapse is
-        // of the
-        // same type as the existing ones
+        // of the same type as the existing ones
         conn = pack_pointer( &vc->push_back( c ), b_has_primary, b_has_secondary );
       }
       else