Merge pull request #3234 from nest/clopath-histentry-doc

Update C++ docstrings for extended histentry

Author: terhorstd

models/clopath_synapse.h

@@ -251,16 +251,18 @@ clopath_synapse< targetidentifierT >::send( Event& e, size_t t, const CommonSyna
   // spike. So we initially read the
   // history(t_last_spike - dendritic_delay, ..., T_spike-dendritic_delay]
   // which increases the access counter for these entries.
-  // At registration, all entries' access counters of
-  // history[0, ..., t_last_spike - dendritic_delay] have been
-  // incremented by ArchivingNode::register_stdp_connection(). See bug #218 for
-  // details.
+
+  // Note that in the STDP synapse, this loop iterates over post spikes,
+  // whereas here we loop over continuous-time history entries (see
+  // histentry_extended).
   target->get_LTP_history( t_lastspike_ - dendritic_delay, t_spike - dendritic_delay, &start, &finish );
-  // facilitation due to postsynaptic activity since last pre-synaptic spike
   while ( start != finish )
   {
     const double minus_dt = t_lastspike_ - ( start->t_ + dendritic_delay );
+
+    // facilitation due to postsynaptic activity since last pre-synaptic spike
     weight_ = facilitate_( weight_, start->dw_, x_bar_ * exp( minus_dt / tau_x_ ) );
+
     ++start;
   }
 

nestkernel/histentry.h

@@ -40,20 +40,25 @@ class histentry
   double t_;              //!< point in time when spike occurred (in ms)
   double Kminus_;         //!< value of Kminus at that time
   double Kminus_triplet_; //!< value of triplet STDP Kminus at that time
-  size_t access_counter_; //!< access counter to enable removal of the entry, once all neurons read it
+  size_t
+    access_counter_; //! how often this entry was accessed (to enable removal, once read by all synapses which need it)
 };
 
-// entry in the history of plasticity rules which consider additional factors
+/**
+ * Class to represent a single entry in the spiking history of the ClopathArchivingNode or the UrbanczikArchivingNode.
+ *
+ * These history entries typically represent continuously-evolving values in time, so history timestamps correspond to
+ * ``nest.biological_time`` in simulation resolution rather than times of spikes.
+ */
 class histentry_extended
 {
 public:
   histentry_extended( double t, double dw, size_t access_counter );
 
-  double t_; //!< point in time when spike occurred (in ms)
+  double t_; //!< point in time for the history entry (in ms)
   double dw_;
-  //! how often this entry was accessed (to enable removal, once read by all
-  //! neurons which need it)
-  size_t access_counter_;
+  size_t
+    access_counter_; //! how often this entry was accessed (to enable removal, once read by all synapses which need it)
 
   friend bool operator<( const histentry_extended he, double t );
 };