docs, test: Fit Sieve of Eratosthenes to contributing guidelines (#2803)

* Update sieve_of_eratosthenes.cpp

* Update doc

---------

Co-authored-by: realstealthninja <[email protected]>

math/sieve_of_eratosthenes.cpp

@@ -1,6 +1,7 @@
 /**
  * @file
- * @brief Get list of prime numbers using Sieve of Eratosthenes
+ * @brief Prime Numbers using [Sieve of
+ * Eratosthenes](https://en.wikipedia.org/wiki/Sieve_of_Eratosthenes)
  * @details
  * Sieve of Eratosthenes is an algorithm that finds all the primes
  * between 2 and N.
@@ -11,21 +12,39 @@
  * @see primes_up_to_billion.cpp prime_numbers.cpp
  */
 
-#include <cassert>
-#include <iostream>
-#include <vector>
+#include <cassert>   /// for assert
+#include <iostream>  /// for IO operations
+#include <vector>    /// for std::vector
 
 /**
- * This is the function that finds the primes and eliminates the multiples.
+ * @namespace math
+ * @brief Mathematical algorithms
+ */
+namespace math {
+/**
+ * @namespace sieve_of_eratosthenes
+ * @brief Functions for finding Prime Numbers using Sieve of Eratosthenes
+ */
+namespace sieve_of_eratosthenes {
+/**
+ * @brief Function to sieve out the primes
+ * @details
+ * This function finds all the primes between 2 and N using the Sieve of
+ * Eratosthenes algorithm. It starts by assuming all numbers (except zero and
+ * one) are prime and then iteratively marks the multiples of each prime as
+ * non-prime.
+ *
  * Contains a common optimization to start eliminating multiples of
  * a prime p starting from p * p since all of the lower multiples
  * have been already eliminated.
- * @param N number of primes to check
- * @return is_prime a vector of `N + 1` booleans identifying if `i`^th number is a prime or not
+ * @param N number till which primes are to be found
+ * @return is_prime a vector of `N + 1` booleans identifying if `i`^th number is
+ * a prime or not
  */
 std::vector<bool> sieve(uint32_t N) {
-    std::vector<bool> is_prime(N + 1, true);
-    is_prime[0] = is_prime[1] = false;
+    std::vector<bool> is_prime(N + 1, true);  // Initialize all as prime numbers
+    is_prime[0] = is_prime[1] = false;        // 0 and 1 are not prime numbers
+
     for (uint32_t i = 2; i * i <= N; i++) {
         if (is_prime[i]) {
             for (uint32_t j = i * i; j <= N; j += i) {
@@ -37,9 +56,10 @@ std::vector<bool> sieve(uint32_t N) {
 }
 
 /**
- * This function prints out the primes to STDOUT
- * @param N number of primes to check
- * @param is_prime a vector of `N + 1` booleans identifying if `i`^th number is a prime or not
+ * @brief Function to print the prime numbers
+ * @param N number till which primes are to be found
+ * @param is_prime a vector of `N + 1` booleans identifying if `i`^th number is
+ * a prime or not
  */
 void print(uint32_t N, const std::vector<bool> &is_prime) {
     for (uint32_t i = 2; i <= N; i++) {
@@ -50,23 +70,53 @@ void print(uint32_t N, const std::vector<bool> &is_prime) {
     std::cout << std::endl;
 }
 
+}  // namespace sieve_of_eratosthenes
+}  // namespace math
+
 /**
- * Test implementations
+ * @brief Self-test implementations
+ * @return void
  */
-void tests() {
-  //                    0      1      2     3     4      5     6      7     8      9      10
-  std::vector<bool> ans{false, false, true, true, false, true, false, true, false, false, false};
-  assert(sieve(10) == ans);
+static void tests() {
+    std::vector<bool> is_prime_1 =
+        math::sieve_of_eratosthenes::sieve(static_cast<uint32_t>(10));
+    std::vector<bool> is_prime_2 =
+        math::sieve_of_eratosthenes::sieve(static_cast<uint32_t>(20));
+    std::vector<bool> is_prime_3 =
+        math::sieve_of_eratosthenes::sieve(static_cast<uint32_t>(100));
+
+    std::vector<bool> expected_1{false, false, true,  true,  false, true,
+                                 false, true,  false, false, false};
+    assert(is_prime_1 == expected_1);
+
+    std::vector<bool> expected_2{false, false, true,  true,  false, true,
+                                 false, true,  false, false, false, true,
+                                 false, true,  false, false, false, true,
+                                 false, true,  false};
+    assert(is_prime_2 == expected_2);
+
+    std::vector<bool> expected_3{
+        false, false, true,  true,  false, true,  false, true,  false, false,
+        false, true,  false, true,  false, false, false, true,  false, true,
+        false, false, false, true,  false, false, false, false, false, true,
+        false, true,  false, false, false, false, false, true,  false, false,
+        false, true,  false, true,  false, false, false, true,  false, false,
+        false, false, false, true,  false, false, false, false, false, true,
+        false, true,  false, false, false, false, false, true,  false, false,
+        false, true,  false, true,  false, false, false, false, false, true,
+        false, false, false, true,  false, false, false, false, false, true,
+        false, false, false, false, false, false, false, true,  false, false,
+        false};
+    assert(is_prime_3 == expected_3);
+
+    std::cout << "All tests have passed successfully!\n";
 }
 
 /**
- * Main function
+ * @brief Main function
+ * @returns 0 on exit
  */
 int main() {
     tests();
-
-    uint32_t N = 100;
-    std::vector<bool> is_prime = sieve(N);
-    print(N, is_prime);
     return 0;
 }