Merged PR 1764144: Doxygen proofreading

Doxygen proofreading

Related work items: #9522889

Author: Yuliya Z. Frolova

knp/backends/cpu/cpu-devices/include/knp/devices/cpu.h

@@ -31,6 +31,7 @@
 
 /**
  * @namespace knp::devices
+ * 
  * @brief Namespace for implementation of concrete devices.
  */
 
@@ -68,6 +69,7 @@ class KNP_DECLSPEC CPU final : public knp::core::Device  // cppcheck-suppress cl
 
     /**
      * @brief CPU device move operator.
+     * 
      * @return reference to CPU instance.
      */
     CPU &operator=(CPU &&) noexcept;
@@ -80,24 +82,28 @@ class KNP_DECLSPEC CPU final : public knp::core::Device  // cppcheck-suppress cl
 public:
     /**
      * @brief Get device type.
+     * 
      * @return device type.
      */
     [[nodiscard]] knp::core::DeviceType get_type() const override;
 
     /**
      * @brief Get device name.
+     * 
      * @return device name in the arbitrary format.
      */
     [[nodiscard]] const std::string get_name() const override;
 
     /**
      * @brief Get CPU device socket number.
+     * 
      * @return socket number.
      */
     [[nodiscard]] uint32_t get_socket_number() const;
 
     /**
      * @brief Get power consumption details for the device.
+     * 
      * @return amount of consumed power.
      */
     [[nodiscard]] float get_power() const override;
@@ -120,6 +126,7 @@ class KNP_DECLSPEC CPU final : public knp::core::Device  // cppcheck-suppress cl
 
 /**
  * @brief List all processors on which backend can be initialized.
+ * 
  * @return vector of CPUs.
  */
 KNP_DECLSPEC std::vector<CPU> list_processors();

knp/backends/cpu/cpu-library/include/knp/backends/cpu-library/init.h

@@ -40,6 +40,7 @@ namespace knp::backends::cpu
 
 /**
  * @brief The "null" subscriber.
+ * 
  * @tparam SynapseType type of the non-STDP synapses.
  */
 template <typename SynapseType>
@@ -54,6 +55,7 @@ struct subscribe_stdp_projection
 
 /**
  * @brief STDP projection subscriber.
+ * 
  * @tparam Rule STDP rule.
  * @tparam SynapseType linked synapse type.
  */
@@ -62,6 +64,7 @@ struct subscribe_stdp_projection<knp::synapse_traits::STDP<Rule, SynapseType>>
 {
     /**
      * @brief Subscribe projection to message endpoint.
+     * 
      * @param p projection to subscribe.
      * @param message_endpoint message endpoint to subscribe.
      */
@@ -81,9 +84,11 @@ struct subscribe_stdp_projection<knp::synapse_traits::STDP<Rule, SynapseType>>
 
 /**
  * @brief Initialize backend.
+ * 
  * @param projections container backend projections.
  * @param message_endpoint message endpoint.
- * @tparam ProjectionContainer type of projection container.
+ * 
+ * @tparam ProjectionContainer type of a projection container.
  */
 template <typename ProjectionContainer>
 void init(const ProjectionContainer &projections, knp::core::MessageEndpoint &message_endpoint)

knp/backends/cpu/cpu-library/include/knp/backends/cpu-library/populations.h

@@ -33,16 +33,22 @@
 
 
 /**
- * @brief Namespace for CPU backend's populations.
+ * @brief Namespace for CPU backend population functions.
  */
 namespace knp::backends::cpu::populations
 {
 
 /**
  * @brief Partially calculate population before it receives synaptic impact messages.
- * @param population Population to update.
- * @param start Index of the first neuron to calculate.
- * @param end Index of the last neuron to calculate.
+ * 
+ * @note The 'end' parameter is exclusive, that is a neuron with the specified 'end' index is not calculated. 
+ * 
+ * @tparam Neuron type of neurons stored in the population.
+ * 
+ * @param population population to calculate.
+ * @param start index of the first neuron to calculate.
+ * @param end index of the last neuron to calculate.
+ * 
  */
 template <class Neuron>
 void calculate_pre_impact_population_state(knp::core::Population<Neuron> &population, size_t start, size_t end)
@@ -56,9 +62,13 @@ void calculate_pre_impact_population_state(knp::core::Population<Neuron> &popula
 
 
 /**
- * @brief Impact population.
- * @param population Population.
- * @param messages Impact messages.
+ * @brief Dispatch synaptic impact messages to population.
+ * 
+ * @tparam Neuron type of neurons stored in the population.
+ * 
+ * @param population population to impact.
+ * @param messages synaptic impact messages to dispatch.
+ * 
  */
 template <class Neuron>
 void impact_population(
@@ -77,10 +87,19 @@ void impact_population(
 
 /**
  * @brief Partially calculate population after it receives synaptic impact messages.
- * @param population population to update.
+ * 
+ * @note The 'end' parameter is exclusive, that is a neuron with the specified 'end' index is not calculated. 
+ * 
+ * @details The function iterates over the neurons in the range `[start, end)`. If a neuron produces a spike, then 
+ * its index is appended to the message defined in the `message` parameter.
+ * 
+ * @tparam Neuron type of neurons stored in the population.
+ * 
+ * @param population population to calculate.
  * @param message output spike message to update.
- * @param start index of the first neuron to update.
- * @param end index of the last neuron to update.
+ * @param start index of the first neuron to calculate.
+ * @param end index of the last neuron to calculate.
+ * 
  */
 template <class Neuron>
 void calculate_post_impact_population_state(
@@ -98,11 +117,16 @@ void calculate_post_impact_population_state(
 
 
 /**
- * @brief Train population.
- * @param population Population.
- * @param projections Connected projections.
- * @param message Spiking neurons in population at current step.
- * @param step Step.
+ * @brief Train the population for the given simulation step.
+ * 
+ * @tparam Neuron type of neurons stored in the population.
+ * @tparam Synapse type of synapses used in the connected projections.
+ * 
+ * @param population population to train.
+ * @param projections connected projections that send synaptic impacts.
+ * @param message spiking neurons in the population at the current step.
+ * @param step simulation step for which the training is performed.
+ * 
  */
 template <class Neuron, class Synapse>
 void train_population(

knp/backends/cpu/cpu-library/include/knp/backends/cpu-library/populations_old.h

@@ -30,19 +30,29 @@
 
 
 /**
- * @brief Namespace for CPU backend's populations.
+ * @brief Namespace for CPU backend functions.
  */
 namespace knp::backends::cpu
 {
 
+
 /**
- * @brief Find projection by type and postsynaptic uid.
+ * @brief Find projections of a given synapse type that target a specific postsynaptic population.
+ * 
  * @tparam SynapseType synapse type.
- * @tparam ProjectionContainer projection container.
- * @param projections projections.
- * @param post_uid postsynaptic uid.
- * @param exclude_locked should projections with locked weights be exluded or not.
- * @return found projections.
+ * @tparam ProjectionContainer type of a projection container.
+ *
+ * @param projections container of projections to search.
+ * @param post_uid UID of the postsynaptic population to match.
+ * @param exclude_locked flag that determines whether projections with locked weights are omitted.
+ *
+ * @return vector of references to the matching projections.
+ *
+ * @details The function iterates over `projections`, skips entries whose variant index does not
+ * match the specified synapse type, and extracts the concrete `Projection<SynapseType>`.  
+ * Projections whose `is_locked()` flag is true are excluded when `exclude_locked` is set.  
+ * Finally, only projections whose postsynaptic population UID matches `post_uid` are added to the result.
+ *
  */
 template <class SynapseType, class ProjectionContainer>
 std::vector<std::reference_wrapper<knp::core::Projection<SynapseType>>> find_projection_by_type_and_postsynaptic(
@@ -74,12 +84,22 @@ std::vector<std::reference_wrapper<knp::core::Projection<SynapseType>>> find_pro
 
 
 /**
- * @brief Make one execution step for a population of any neurons.
- * @tparam Neuron type of a neuron.
+ * @brief Execute one simulation step for a population of arbitrary neurons.
+ *
+ * @tparam Neuron type of neurons stored in the population.
+ *
  * @param pop population to update.
- * @param endpoint message endpoint used for message exchange.
- * @param step_n execution step.
- * @return indexes of spiked neurons.
+ * @param endpoint message endpoint used for loading and sending messages.
+ * @param step_n current execution step number.
+ *
+ * @return spike message containing the indexes of neurons that emitted a spike during this step.
+ *
+ * @details The function unloads all synaptic impact messages addressed to the population from 
+ * the message endpoint. Then the function calculates pre-impact state 
+ * (@ref populations::calculate_pre_impact_population_state), dispatches synaptic impact messages
+ * (@ref populations::impact_population), and calculates post-impact state 
+ * (@ref populations::calculate_post_impact_population_state). If any spikes were generated, 
+ * the functions sends a spike message back through the message endpoint.
  */
 template <class Neuron>
 std::optional<core::messaging::SpikeMessage> calculate_any_population(
@@ -102,12 +122,19 @@ std::optional<core::messaging::SpikeMessage> calculate_any_population(
 
 
 /**
- * @brief Make one execution step for a population of BLIFAT neurons.
- * @tparam BlifatLikeNeuron type of a neuron with BLIFAT-like parameters.
+ * @brief Execute one simulation step for a population of BLIFAT‑like neurons.
+ *
+ * @tparam BlifatLikeNeuron type of a neuron that possesses BLIFAT‑like parameters.
+ *
  * @param pop population to update.
- * @param endpoint message endpoint used for message exchange.
- * @param step_n execution step.
- * @return indexes of spiked neurons.
+ * @param endpoint message endpoint used for loading and sending messages.
+ * @param step_n current execution step number.
+ *
+ * @return spike message containing the indexes of neurons that emitted a spike during this step.
+ *
+ * @details This function is a thin wrapper around @ref calculate_any_population. It forwards the provided population,
+ *  message endpoint, and step number to the generic implementation, thereby reusing the full simulation pipeline.
+ *
  */
 template <class BlifatLikeNeuron>
 std::optional<core::messaging::SpikeMessage> calculate_blifat_population(
@@ -118,12 +145,19 @@ std::optional<core::messaging::SpikeMessage> calculate_blifat_population(
 
 
 /**
- * @brief Calculate LIF population.
+ * @brief Execute one simulation step for a population of LIF neurons.
+ *
  * @tparam LifNeuron LIF neuron type.
- * @param pop population to calculate.
- * @param endpoint endpoint to use for message exchange.
- * @param step_n current step.
- * @return spike message with indexes of spiked neurons if population is emitting one.
+ *
+ * @param pop population to update.
+ * @param endpoint message endpoint used for loading and sending messages.
+ * @param step_n current execution step number.
+ *
+ * @return spike message containing the indexes of neurons that emitted a spike during this step.
+ *
+ * @details This function simply forwards the call to @ref calculate_any_population, reusing the 
+ * generic simulation pipeline.
+ *
  */
 template <class LifNeuron>
 std::optional<knp::core::messaging::SpikeMessage> calculate_lif_population(
@@ -133,16 +167,30 @@ std::optional<knp::core::messaging::SpikeMessage> calculate_lif_population(
 }
 
 
-/**
- * @brief Make one execution step for a population of `SynapticResourceSTDPNeuron` neurons.
- * @tparam BlifatLikeNeuron type of a neuron with BLIFAT-like parameters.
+ /**
+ * @brief Execute one simulation step for a population of `SynapticResourceSTDPNeuron` neurons.
+ *
+ * @tparam BlifatLikeNeuron type of a neuron with BLIFAT‑like parameters.
  * @tparam BaseSynapseType base synapse type.
  * @tparam ProjectionContainer type of a projection container.
+ *
  * @param pop population to update.
- * @param container projection container from backend.
- * @param endpoint message endpoint used for message exchange.
- * @param step_n execution step.
- * @return message containing indexes of spiked neurons.
+ * @param container projection container supplied by the backend.
+ * @param endpoint message endpoint used for loading and sending messages.
+ * @param step_n current execution step number.
+ *
+ * @return spike message containing the indexes of neurons that emitted a spike during this step.
+ *
+ * @details The function unloads all synaptic impact messages addressed to the population from 
+ * the message endpoint. Then the function calculates pre-impact state 
+ * (@ref populations::calculate_pre_impact_population_state), dispatches synaptic impact messages
+ * (@ref populations::impact_population), and calculates post-impact state 
+ * (@ref populations::calculate_post_impact_population_state). 
+ * The function then retrieves projections of the `SynapticResourceSTDPDeltaSynapse` type that 
+ * target the population, optionally excluding locked ones. 
+ * Finally, the function trains the population with the generated spike message and sends the spike 
+ * message back through the message endpoint if any neurons spiked.
+
  */
 template <class BlifatLikeNeuron, class BaseSynapseType, class ProjectionContainer>
 std::optional<core::messaging::SpikeMessage> calculate_resource_stdp_population(

knp/backends/cpu/cpu-library/include/knp/backends/cpu-library/projections.h

@@ -33,15 +33,27 @@
 #include "impl/projections/projection_dispatcher.h"
 
 
+/**
+ * @brief Namespace for CPU backend projection functions.
+ */
 namespace knp::backends::cpu::projections
 {
 
 /**
- * @brief Calculate projection.
- * @param projection Projection.
- * @param endpoint Projection endpoint.
- * @param future_messages Future messages queue.
- * @param step_n Step number.
+ * @brief Calculate a synapse projection for the given simulation step.
+ *
+ * @tparam Synapse type of a synapse that possesses Delta‑like parameters.
+ *
+ * @param projection projection to calculate.
+ * @param endpoint message endpoint used for loading and sending messages.
+ * @param future_messages queue that stores messages to be sent in future steps.
+ * @param step_n current simulation step number.
+ *
+ * @details First, the function unloads all spike messages addressed to the projection from
+ * the message endpoint. Then the function processes the unloaded spike messages together with 
+ * any pending `future_messages` and returns an iterator to the first impact message that should be
+ *  sent immediately. If such a message exists, the function sends it via the message endpoint
+ *  and removes it from `future_messages`.
  */
 template <typename Synapse>
 void calculate_projection(
@@ -73,16 +85,20 @@ void calculate_projection(
 
 
 /**
- * @brief Process a part of projection synapses in multithreaded way.
- * @pre TODO Get rid of this function. Its here just so multi threaded backend will work.
- * @tparam Synapse type of a synapse that requires synapse weight and delay as parameters.
- * @param projection projection to receive the message.
+ * @brief Process a part of projection synapses in a multi-threaded way.
+ *
+ * @todo Get rid of this function. This function exists only to keep the multi-threaded backend functional.
+ *
+ * @tparam Synapse type of synapses stored in the projection.
+ *
+ * @param projection projection that will receive the processed messages.
  * @param message_in_data processed spike data for the projection.
  * @param future_messages queue of future messages.
- * @param step_n current step.
+ * @param step_n current simulation step.
  * @param part_start index of the starting synapse.
  * @param part_size number of synapses to process.
- * @param mutex mutex.
+ * @param mutex mutex used for synchronization.
+ *
  */
 template <class Synapse>
 void calculate_projection_multithreaded(