Docstrings and comments added to secure history aggregator

Author: mina5rovic

discojs/src/aggregator/secure_history.spec.ts

@@ -92,6 +92,7 @@ describe("Secure history aggregator", function () {
         const avgPartialSum = aggregation.avg(partialSums);
         expect(sumRound1.equals(avgPartialSum, epsilon)).to.be.true;
 
+        // Now we simulate a second round of aggregation with momentum smoothing
         const dummyPromise = aggregator.getPromiseForAggregation();
         partialSums.forEach((partialSum, idx) => {
             const nodeId = idx.toString();
@@ -105,7 +106,7 @@ describe("Secure history aggregator", function () {
             ws.map((tensor) => tf.mul(tensor, 1.1))
         );
 
-        // Step 3: Add new partial sums to aggregator
+        // Add the modified partial sums to the aggregator
         partialSums2.forEach((partialSum, idx) => {
             const nodeId = idx.toString();
             aggregator.add(nodeId, partialSum, 1);
@@ -117,7 +118,7 @@ describe("Secure history aggregator", function () {
             prev.mul(0.8).add(curr.mul(0.2)) // 0.8 = beta, 0.2 = (1 - beta)
         );
 
-        // Compare the actual result to the expected smoothed result
+        // Compare the actual result to the expected smoothed result using momentum
         expect(sumRound2.equals(expectedSumRound2, 1e-3)).to.be.true;
     });
 

discojs/src/aggregator/secure_history.ts

@@ -3,10 +3,30 @@ import { SecureAggregator } from "./secure.js";
 import * as tf from "@tensorflow/tfjs";
 import { aggregation } from "../index.js";
 
+/**
+ * Aggregator that implements secure multi-party computation with history-based momentum smoothing.
+ * It aggregates contributions in two communication rounds:
+ * - In the first round, nodes send their secret shares to each other.
+ * - In the second round, they sum their received shares and communicate the result.
+ * Finally, nodes average the received partial sums to establish the aggregation result.
+ * This aggregator also applies momentum smoothing based on the previous aggregation result.
+ * It uses a beta parameter to control the smoothing effect.
+ * The first aggregation round uses the average of contributions, while subsequent rounds apply momentum smoothing.
+ * This allows for a more stable aggregation result over time, reducing the impact of outliers.
+ * * @extends SecureAggregator
+ * * @example
+ * const aggregator = new SecureHistoryAggregator(100, 0.9);
+ */
+
 export class SecureHistoryAggregator extends SecureAggregator {
   private prevAggregate: WeightsContainer | null = null;
   private readonly beta: number;
 
+  /**
+   * @param maxShareValue - The maximum value for each share.
+   * @param beta - The momentum smoothing factor (0 < beta < 1).
+   */
+
   constructor(maxShareValue = 100, beta = 0.9) {
     super(maxShareValue);
     this.beta = beta;