Merge pull request #2113 from jessica-mitchell/cleanup-cpp-docs

Clean up doxygen comments in nestkernel directory

doc/htmldoc/developer_space/cppcomments.rst

@@ -0,0 +1,82 @@
+Guidelines for C++ code comments
+================================
+
+There are two types of code comments for C++ files: doxygen style and C++ style comments.
+
+* Doxygen styled comments are used for describing things like the purpose of the function, which parameters it accepts, and what output it generates.
+* Use Doxygen style comments in the header (``.h``)  files. Avoid using them in ``.cpp`` files.
+* Do not duplicate code in comments.
+..  Include the variable name in functions in header file to match cpp file.
+
+
+Generate HTML from doxygen comments
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To generate HTML output of the doxgyen comments,
+
+in the build directory, 
+
+run ``cmake`` with developer documentation on::
+
+  cmake -Dwith-devdoc=ON path/to/nest-simulator.
+
+then
+
+::
+
+   make docs
+   xdg-open doc/doxygen/html/index.html
+
+.. seealso::
+
+  See `the official doxygen documentation <https://www.doxygen.nl/>`_ for details.
+
+
+Doxygen style
+~~~~~~~~~~~~~
+
+* Multi-line comments
+
+.. code-block:: cpp
+
+  /**
+   * Short description
+   *
+   * Further details, if necesary
+   */
+
+.. note::
+
+    Functions and classes should use the multi-line style even for single line comments.
+
+* Single or two line comments to use with variables:
+
+.. code-block:: cpp
+
+   //! The maximum delay of the simulation
+   long may_delay;
+
+
+* If a short comment is needed for variables, you can add a comment to the right of the code:
+
+.. code-block:: cpp
+
+  long max_delay_; //!< The maximum delay of the simulation
+
+C++ style
+~~~~~~~~~
+
+* Multi-line comments:
+
+.. code-block:: cpp
+
+   //
+   //
+   //
+   //
+
+  * Single or two line comments:
+
+.. code-block:: cpp
+
+ //

nestkernel/archiving_node.h

@@ -49,68 +49,37 @@ namespace nest
 class ArchivingNode : public StructuralPlasticityNode
 {
 public:
-  /**
-   * \fn ArchivingNode()
-   * Constructor.
-   */
   ArchivingNode();
 
-  /**
-   * \fn ArchivingNode()
-   * Copy Constructor.
-   */
   ArchivingNode( const ArchivingNode& );
 
   /**
-   * \fn double get_K_value(long t)
-   * return the Kminus (synaptic trace) value at t (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.
+   * 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.
    */
   double get_K_value( double t ) override;
 
   /**
-   * \fn void get_K_values( double t,
-   *   double& Kminus,
-   *   double& nearest_neighbor_Kminus,
-   *   double& Kminus_triplet )
-   * write the Kminus (eligibility trace for STDP),
-   * nearest_neighbour_Kminus (eligibility trace for nearest-neighbour STDP:
-   *   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.
+   * Write the different STDP K values at time t (in ms) to the provided locations.
+   *
+   * @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
+   *
    * @throws UnexpectedEvent
    */
   void get_K_values( double t, double& Kminus, double& nearest_neighbor_Kminus, double& Kminus_triplet ) override;
 
   /**
-   * \fn void get_K_values( double t,
-   *   double& Kminus,
-   *   double& Kminus_triplet )
-   * The legacy version of the function, 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 );
-  }
-
-  /**
-   * \fn double get_K_triplet_value(std::deque<histentry>::iterator &iter)
-   * return the triplet Kminus value for the associated iterator.
+   * Return the triplet Kminus value for the associated iterator.
    */
   double get_K_triplet_value( const std::deque< histentry >::iterator& iter );
 
   /**
-   * \fn void get_history(long t1, long t2,
-   * std::deque<Archiver::histentry>::iterator* start,
-   * std::deque<Archiver::histentry>::iterator* finish)
-   * 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,26 +99,26 @@ class ArchivingNode : public StructuralPlasticityNode
 
 protected:
   /**
-   * \fn void set_spiketime(Time const & t_sp, double offset)
-   * record spike history
+   * Record spike history
    */
   void set_spiketime( Time const& t_sp, double offset = 0.0 );
 
   /**
-   * \fn double get_spiketime()
-   * return most recent spike time in ms
+   * Return most recent spike time in ms
    */
   inline double get_spiketime_ms() const;
 
   /**
-   * \fn void clear_history()
-   * clear spike history
+   * Clear spike history
    */
   void clear_history();
 
-  // number of incoming connections from stdp connectors.
-  // needed to determine, if every incoming connection has
-  // read the spikehistory for a given point in time
+  /**
+   * Number of incoming connections from STDP connectors.
+   *
+   * This variable is needed to determine if every incoming connection has
+   * read the spikehistory for a given point in time
+   */
   size_t n_incoming_;
 
 private:

nestkernel/clopath_archiving_node.cpp

@@ -64,12 +64,6 @@ nest::ClopathArchivingNode::ClopathArchivingNode( const ClopathArchivingNode& n
 void
 nest::ClopathArchivingNode::init_clopath_buffers()
 {
-  // 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.
   delayed_u_bars_idx_ = 0;
   delay_u_bars_steps_ = Time::delay_ms_to_steps( delay_u_bars_ ) + 1;
   delayed_u_bar_plus_.resize( delay_u_bars_steps_ );
@@ -170,6 +164,7 @@ nest::ClopathArchivingNode::get_LTP_history( double t1,
   else
   {
     std::deque< histentry_extended >::iterator runner = ltp_history_.begin();
+
     // To have a well defined discretization of the integral, we make sure
     // that we exclude the entry at t1 but include the one at t2 by subtracting
     // a small number so that runner->t_ is never equal to t1 or t2.

nestkernel/clopath_archiving_node.h

@@ -40,36 +40,23 @@ namespace nest
 {
 
 /**
- * \class ClopathArchivingNode
- * a archiving node which additionally archives parameters
+ * An archiving node which additionally archives parameters
  * and buffers needed for the Clopath plasticity rule
  */
 class ClopathArchivingNode : public ArchivingNode
 {
 
 public:
-  /**
-   * \fn ClopathArchivingNode()
-   * Constructor.
-   */
   ClopathArchivingNode();
 
-  /**
-   * \fn ClopathArchivingNode()
-   * Copy Constructor.
-   */
   ClopathArchivingNode( const ClopathArchivingNode& );
 
   /**
-   * \fn double get_LTD_value(long t)
    * Returns value in LTD history at time t
    */
   double get_LTD_value( double t ) override;
 
   /**
-   * \fn void get_LTP_history(long t1, long t2,
-   * std::deque<Archiver::histentry>::iterator* start,
-   * std::deque<Archiver::histentry>::iterator* finish)
    * Sets pointer start (finish) to the first (last) entry in LTP_history
    * whose time argument is between t1 and t2
    */
@@ -79,43 +66,44 @@ class ClopathArchivingNode : public ArchivingNode
     std::deque< histentry_extended >::iterator* finish ) override;
 
   /**
-   * \fn double get_theta_plus()
    * Returns threshold theta_plus_
    */
   double get_theta_plus() const;
 
   /**
-   * \fn double get_theta_minus()
    * Returns threshold theta_minus_
    */
   double get_theta_minus() const;
 
 protected:
   /**
-   * \fn void write_LTD_history( Time const& t_sp,
-   * double u_bar_minus, double u_bar_bar )
    * Creates a new entry in the LTD history and deletes old entries that
    * are not needed any more.
    */
   void write_LTD_history( const double t_ltd_ms, double u_bar_minus, double u_bar_bar );
 
   /**
-   * \fn void write_LTP_history( const double t_ltp_ms, double u,
-   * double u_bar_plus )
    * Creates a new entry in the LTP history and delets old entries that
    * are not needed any more.
    */
   void write_LTP_history( const double t_ltp_ms, double u, double u_bar_plus );
 
   /**
-   * \fn void write_clopath_history( Time const& t_sp,
-   * double u, double u_bar_plus, double u_bar_minus, double u_bar_bar )
    * Writes and reads the delayed_u_bar_[plus/minus] buffers and
    * calls write_LTD_history and write_LTP_history if
    * the corresponding Heaviside functions yield 1.
    */
   void write_clopath_history( Time const& t_sp, double u, double u_bar_plus, double u_bar_minus, double u_bar_bar );
 
+  /**
+   * 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: static_synapse
-*/
-
 // Includes from nestkernel:
 #include "common_synapse_properties.h"
 
@@ -48,19 +35,12 @@ namespace nest
 class CommonPropertiesHomW : public CommonSynapseProperties
 {
 public:
-  /**
-   * Default constructor.
-   * 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
   {
@@ -91,4 +71,4 @@ class CommonPropertiesHomW : public CommonSynapseProperties
 
 } // namespace nest
 
-#endif // COMMON_PROPERTIES_HOM_W_H
+#endif /* #ifndef COMMON_PROPERTIES_HOM_W_H */

nestkernel/common_synapse_properties.cpp

@@ -34,10 +34,6 @@
 namespace nest
 {
 
-/**
- * Default implementation of an empty CommonSynapseProperties object.
- */
-
 CommonSynapseProperties::CommonSynapseProperties()
   : weight_recorder_()
   , wr_node_id_( 0 )