Merge pull request #19 from jougs/cleanup-cpp-docs

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

Author: jessica-mitchell

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  |
 +----------------------------------+-------------+

pynest/examples/Potjans_2014/box_plot.png doc/htmldoc/static/img/box_plot.pngpynest/examples/Potjans_2014/box_plot.png renamed to doc/htmldoc/static/img/box_plot.png

@@ -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/htmldoc/static/img/microcircuit.png

@@ -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

…st/examples/Potjans_2014/raster_plot.png doc/htmldoc/static/img/raster_plot.pngpynest/examples/Potjans_2014/raster_plot.png renamed to doc/htmldoc/static/img/raster_plot.png pynest/examples/Potjans_2014/raster_plot.png renamed to doc/htmldoc/static/img/raster_plot.png

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

doc/htmldoc/templates/index.html

@@ -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_;