Final run-through and further cleanup of differen types of comments

doc/htmldoc/404.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+404 - Page not found
+--------------------
+
+
+Sorry, it looks like the page you were looking for doesn't exist in this version or has moved.
+
+Try the search bar or the navigation sidebar.
+
+

doc/htmldoc/conf.py

@@ -59,6 +59,7 @@
     "HoverXTooltip",
     "VersionSyncRole",
     "sphinx_copybutton",
+    "notfound.extension",
 ]
 
 autodoc_mock_imports = ["nest.pynestkernel", "nest.ll_api"]
@@ -81,6 +82,9 @@
 copyright = "2004, nest-simulator"
 author = "nest-simulator"
 
+copybutton_prompt_text = ">>> "
+# The output lines will not be copied if set to True
+copybutton_only_copy_prompt_lines = True
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -354,9 +358,6 @@ def copy_example_file(src):
 
 
 # -- Copy documentation for Microcircuit Model ----------------------------
-copy_example_file("examples/Potjans_2014/box_plot.png")
-copy_example_file("examples/Potjans_2014/raster_plot.png")
-copy_example_file("examples/Potjans_2014/microcircuit.png")
 copy_example_file("examples/hpc_benchmark_connectivity.svg")
 
 

doc/htmldoc/developer_space/guidelines/naming_conventions.rst

@@ -6,36 +6,55 @@ Variables and parameter names
 Conventions for parameters
 --------------------------
 
-1. Do not use capitalization to indicate whether a value in the status dictionary is variable.
-1. Where available, use the notation from P.Dayan & L.F.Abbott, Theoretical Neuroscience, MIT Press, 2001.
-1. Where not available, use a notation that is consistent with Dayan & Abbott.
-1. Subscripts are indicated by underscores
+#. Do not use capitalization to indicate whether a value in the status dictionary is variable.
+#. Where available, use the notation from P.Dayan & L.F.Abbott, Theoretical Neuroscience, MIT Press, 2001.
+#. Where not available, use a notation that is consistent with Dayan & Abbott.
+#. Subscripts are indicated by underscores
 
 Parameters and symbols
 ----------------------
 
 +----------------------------------+-------------+
 | PARAMETER                        | SYMBOL/NAME |
-+----------------------------------+-------------+
++==================================+=============+
 | Membrane potential               | V_m         |
++----------------------------------+-------------+
 | Resting potential                | E_L         |
++----------------------------------+-------------+
 | Input current                    | I_e         |
++----------------------------------+-------------+
 | Leak current                     | I_L         |
++----------------------------------+-------------+
 | Threshold                        | V_th        |
++----------------------------------+-------------+
 | Reset Potential                  | V_reset     |
++----------------------------------+-------------+
 | Capacity or specific capacitance | c_m         |
++----------------------------------+-------------+
 | Capacitance                      | C_m         |
++----------------------------------+-------------+
 | Membrane time const.             | tau_m       |
++----------------------------------+-------------+
 | Synapse time constant            | tau_syn     |
++----------------------------------+-------------+
 | Refractory period                | t_ref       |
++----------------------------------+-------------+
 | Time of last spike               | t_spike     |
++----------------------------------+-------------+
 | Excitatory reversal potential    | E_ex        |
++----------------------------------+-------------+
 | Inhibitory reversal potential    | E_in        |
++----------------------------------+-------------+
 | Conductance                      | g           |
++----------------------------------+-------------+
 | Leak conductance                 | g_L         |
++----------------------------------+-------------+
 | Sodium conductance               | g_Na        |
++----------------------------------+-------------+
 | Sodium reversal potential        | E_Na        |
++----------------------------------+-------------+
 | Potassium conductance            | g_K         |
++----------------------------------+-------------+
 | Potassium reversal potential     | E_K         |
 +----------------------------------+-------------+
 
@@ -44,13 +63,20 @@ Common suffixes (subscripts)
 
 +----------------------------------+-------------+
 | SUBSCRIPT                        | MEANING     |
-+----------------------------------+-------------+
++==================================+=============+
 | m                                | membrane    |
++----------------------------------+-------------+
 | L                                | leak        |
++----------------------------------+-------------+
 | e                                | extern      |
++----------------------------------+-------------+
 | th                               | threshold   |
++----------------------------------+-------------+
 | syn                              | synapse     |
++----------------------------------+-------------+
 | ref                              | refractory  |
++----------------------------------+-------------+
 | ex                               | excitatory  |
++----------------------------------+-------------+
 | in                               | inhibitory  |
 +----------------------------------+-------------+

doc/htmldoc/templates/index.html

@@ -190,7 +190,7 @@ <h1>Learning from example</h1>
             <div class="grid_10">
               Our <a href="examples/index.html">extensive list of example scripts</a> showcase the many models
               and methods you can use for your project. <br>
-              We also have network models of varyinig scales like the <a
+              We also have network models of varying scales like the <a
                 href="examples/cortical_microcircuit_index.html">microcircuit model</a>
               and the <a href="https://inm-6.github.io/multi-area-model/">multi-area model</a>.
             </div>

doc/requirements.txt

@@ -23,6 +23,7 @@ seaborn==0.12.2
 sphinx==6.2.1
 sphinx_autobuild==2021.3.14
 sphinx-copybutton>=0.5.2
+sphinx-notfound-page>=0.8.3
 sphinx-design==0.4.1
 sphinx-gallery==0.13.0
 sphinx-material==0.0.35

environment.yml

@@ -111,3 +111,4 @@ dependencies:
     - sphinx_design
     - sphinx-material
     - sphinx-copybutton
+    - sphinx-notfound-page

nestkernel/archiving_node.h

@@ -54,46 +54,32 @@ class ArchivingNode : public StructuralPlasticityNode
   ArchivingNode( const ArchivingNode& );
 
   /**
-   * Return the Kminus (synaptic trace) value at t (in ms).
+   * Return the Kminus (synaptic trace) value at time t (given in ms).
    *
-   * When the trace is requested at the exact same time that
-   * the neuron emits a spike, the trace
-   * value as it was just before the spike is returned.
+   * When the trace is requested at the exact same time that the neuron emits a spike,
+   * the trace value as it was just before the spike is returned.
    */
   double get_K_value( double t ) override;
 
   /**
-   * Write the Kminus (eligibility trace for STDP),
-   * nearest_neighbour_Kminus (eligibility trace for nearest-neighbour STDP
+   * Write the different STDP K values at time t (in ms) to the provided locations.
    *
-   * Like Kminus, but increased to 1, rather than by 1, on a spike
-   * occurrence), and Kminus_triplet values at t (in ms) to the provided locations.
-   * @throws UnexpectedEvent
-   */
-  void get_K_values( double t, double& Kminus, double& nearest_neighbor_Kminus, double& Kminus_triplet ) override;
-
-  /**
-   * The legacy version of the function
+   * @param Kminus the eligibility trace for STDP
+   * @param nearest_neighbour_Kminus eligibility trace for nearest-neighbour STDP, like Kminus,
+                                     but increased to 1, rather than by 1, when a spike occurs
+   * @param Kminus_triplet eligibility trace for triplet STDP
    *
-   * Kept for compatibility
-   * after changing the function signature in PR #865.
    * @throws UnexpectedEvent
    */
-  void
-  get_K_values( double t, double& Kminus, double& Kminus_triplet )
-  {
-    double nearest_neighbor_Kminus_to_discard;
-    get_K_values( t, Kminus, nearest_neighbor_Kminus_to_discard, Kminus_triplet );
-  }
+  void get_K_values( double t, double& Kminus, double& nearest_neighbor_Kminus, double& Kminus_triplet ) override;
 
   /**
    * Return the triplet Kminus value for the associated iterator.
    */
   double get_K_triplet_value( const std::deque< histentry >::iterator& iter );
 
   /**
-   * Return the spike times (in steps) of spikes which occurred in the range
-   * [t1,t2].
+   * Return the spike times (in steps) of spikes which occurred in the range [t1,t2].
    */
   void get_history( double t1,
     double t2,
@@ -130,7 +116,7 @@ class ArchivingNode : public StructuralPlasticityNode
   /**
    * Number of incoming connections from STDP connectors.
    *
-   * It is needed to determine, if every incoming connection has
+   * This variable is needed to determine if every incoming connection has
    * read the spikehistory for a given point in time
    */
   size_t n_incoming_;

nestkernel/clopath_archiving_node.h

@@ -96,14 +96,14 @@ class ClopathArchivingNode : public ArchivingNode
   void write_clopath_history( Time const& t_sp, double u, double u_bar_plus, double u_bar_minus, double u_bar_bar );
 
   /**
-   * Implementation of the delay of the convolved membrane potentials. This
-   * delay is not described in Clopath et al. 2010 but is present in the code
-   * (https://senselab.med.yale.edu/ModelDB/showmodel.cshtml?model=144566) on
-   * ModelDB which was presumably used to create the figures in the paper.
-   * Since we write into the buffer before we read from it, we have to
-   * add 1 to the size of the buffers.
+   * Initialization of buffers.
+   *
+   * The implementation of the delay of the convolved membrane potentials as used
+   * here is not described in Clopath et al. 2010, but is present in the code
+   * on ModelDB (https://senselab.med.yale.edu/ModelDB/showmodel.cshtml?model=144566)
+   * which was presumably used to create the figures in the paper. Since we write
+   * into the buffer before we read from it, we have to add 1 to the size of the buffers.
    */
-
   void init_clopath_buffers();
   void get_status( DictionaryDatum& d ) const override;
   void set_status( const DictionaryDatum& d ) override;

nestkernel/common_properties_hom_w.h

@@ -23,19 +23,6 @@
 #ifndef COMMON_PROPERTIES_HOM_W_H
 #define COMMON_PROPERTIES_HOM_W_H
 
-/** @BeginDocumentation
-
-   Name: static_synapse_hom_w - Static synapse type
-        using homogeneous weight, i.e. all synapses
-         feature the same w.
-
-   FirstVersion: April 2008
-
-   Author: Moritz Helias, Susanne Kunkel
-
-   SeeAlso: synapsedict, static_synapse
- */
-
 // Includes from nestkernel:
 #include "common_synapse_properties.h"
 
@@ -48,18 +35,12 @@ namespace nest
 class CommonPropertiesHomW : public CommonSynapseProperties
 {
 public:
-  /**
-   * Sets all property values to defaults.
-   */
   CommonPropertiesHomW()
     : CommonSynapseProperties()
     , weight_( 1.0 )
   {
   }
 
-  /**
-   * Get all properties and put them into a dictionary.
-   */
   void
   get_status( DictionaryDatum& d ) const
   {
@@ -90,4 +71,4 @@ class CommonPropertiesHomW : public CommonSynapseProperties
 
 } // namespace nest
 
-#endif /* COMMON_PROPERTIES_HOM_W_H */
+#endif /* #ifndef COMMON_PROPERTIES_HOM_W_H */

nestkernel/conn_builder.cpp

@@ -55,17 +55,14 @@ nest::ConnBuilder::ConnBuilder( NodeCollectionPTR sources,
   , parameters_requiring_skipping_()
   , param_dicts_()
 {
-  /* read out rule-related parameters
-   * - /rule has been taken care of above
-   * - rule-specific params are handled by subclass c'tor
-   */
+  // We only read a subset of rule-related parameters here. The property 'rule'
+  // has already been taken care of in ConnectionManager::get_conn_builder() and
+  // rule-specific parameters are handled by the subclass constructors.
   updateValue< bool >( conn_spec, names::allow_autapses, allow_autapses_ );
   updateValue< bool >( conn_spec, names::allow_multapses, allow_multapses_ );
   updateValue< bool >( conn_spec, names::make_symmetric, make_symmetric_ );
 
-  // read out synapse-related parameters ----------------------
-
-  // synapse-specific parameters that should be skipped when we set default synapse parameters
+  // Synapse-specific parameters that should be skipped when we set default synapse parameters
   skip_syn_params_ = {
     names::weight, names::delay, names::min_delay, names::max_delay, names::num_connections, names::synapse_model
   };
@@ -91,8 +88,7 @@ nest::ConnBuilder::ConnBuilder( NodeCollectionPTR sources,
     DictionaryDatum syn_defaults = kernel().model_manager.get_connector_defaults( synapse_model_id_[ synapse_indx ] );
 
 #ifdef HAVE_MUSIC
-    // We allow music_channel as alias for receptor_type during
-    // connection setup
+    // We allow music_channel as alias for receptor_type during connection setup
     ( *syn_defaults )[ names::music_channel ] = 0;
 #endif
 
@@ -101,7 +97,7 @@ nest::ConnBuilder::ConnBuilder( NodeCollectionPTR sources,
 
   set_structural_plasticity_parameters( syn_specs );
 
-  // If make_symmetric_ is requested call reset on all parameters in order
+  // If make_symmetric_ is requested, call reset on all parameters in order
   // to check if all parameters support symmetric connections
   if ( make_symmetric_ )
   {
@@ -147,8 +143,8 @@ nest::ConnBuilder::~ConnBuilder()
 bool
 nest::ConnBuilder::change_connected_synaptic_elements( size_t snode_id, size_t tnode_id, const size_t tid, int update )
 {
-
   int local = true;
+
   // check whether the source is on this mpi machine
   if ( kernel().node_manager.is_local_node_id( snode_id ) )
   {
@@ -183,6 +179,7 @@ nest::ConnBuilder::change_connected_synaptic_elements( size_t snode_id, size_t t
       target->connect_synaptic_element( post_synaptic_element_name_, update );
     }
   }
+
   return local;
 }
 
@@ -447,11 +444,9 @@ nest::ConnBuilder::set_default_weight_or_delay_( DictionaryDatum syn_params, siz
 
   default_delay_[ synapse_indx ] = not syn_params->known( names::delay );
 
-  /*
-   * If neither weight nor delay are given in the dict, we handle this separately. Important for
-   * hom_w synapses, on which weight cannot be set. However, we use default weight and delay for
-   * _all_ types of synapses.
-   */
+  // If neither weight nor delay are given in the dict, we handle this separately. Important for
+  // hom_w synapses, on which weight cannot be set. However, we use default weight and delay for
+  // _all_ types of synapses.
   default_weight_and_delay_[ synapse_indx ] = ( default_weight_[ synapse_indx ] and default_delay_[ synapse_indx ] );
 
   if ( not default_weight_and_delay_[ synapse_indx ] )
@@ -604,11 +599,9 @@ nest::OneToOneBuilder::connect_()
 
       if ( loop_over_targets_() )
       {
-        /*
-         * A more efficient way of doing this might be to use NodeCollection's local_begin(). For this to work we would
-         * need to change some of the logic, sources and targets might not be on the same process etc., so therefore
-         * we are not doing it at the moment. This also applies to other ConnBuilders below.
-         */
+        // A more efficient way of doing this might be to use NodeCollection's local_begin(). For this to work we would
+        // need to change some of the logic, sources and targets might not be on the same process etc., so therefore
+        // we are not doing it at the moment. This also applies to other ConnBuilders below.
         NodeCollection::const_iterator target_it = targets_->begin();
         NodeCollection::const_iterator source_it = sources_->begin();
         for ( ; target_it < targets_->end(); ++target_it, ++source_it )