docs: Enhance polynomial functions with detailed documentation for inversion and multiplication

Author: weilycoder

weilycoder/poly/elementary_func/inverse.hpp

@@ -1,13 +1,31 @@
 #ifndef WEILYCODER_POLY_ELEMENTARY_FUNC_INVERSE_HPP
 #define WEILYCODER_POLY_ELEMENTARY_FUNC_INVERSE_HPP
 
+/**
+ * @file inverse.hpp
+ * @brief Polynomial Inversion functions using Newton's method and NTT.
+ */
+
 #include "../../number_theory/mod_utility.hpp"
 #include "../ntt_convolve.hpp"
 #include "multiply.hpp"
 #include <stdexcept>
 #include <vector>
 
 namespace weilycoder {
+/**
+ * @brief Compute the inverse of a polynomial modulo x^n using Newton's method.
+ * @tparam T Coefficient type.
+ * @tparam MultiplyFunc Type of the multiplication function.
+ * @tparam SubtractFunc Type of the subtraction function.
+ * @tparam InverseFunc Type of the inversion function for coefficients.
+ * @param a Coefficients of the polynomial to be inverted.
+ * @param n Degree up to which the inverse is computed (result size will be n).
+ * @param multiply Function to multiply two polynomials.
+ * @param number_sub Function to subtract two coefficients.
+ * @param number_inv Function to compute the multiplicative inverse of a coefficient.
+ * @return Coefficients of the inverse polynomial modulo x^n.
+ */
 template <typename T, typename MultiplyFunc, typename SubtractFunc,
           typename InverseFunc>
 std::vector<T> poly_inv(const std::vector<T> &a, size_t n, MultiplyFunc multiply,
@@ -26,6 +44,14 @@ std::vector<T> poly_inv(const std::vector<T> &a, size_t n, MultiplyFunc multiply
   return res;
 }
 
+/**
+ * @brief Compute the inverse of a polynomial modulo x^n using NTT
+ *        under a given modulus.
+ * @tparam mod Modulus for NTT.
+ * @param a Coefficients of the polynomial to be inverted.
+ * @param n Degree up to which the inverse is computed (result size will be n).
+ * @return Coefficients of the inverse polynomial modulo x^n.
+ */
 template <uint64_t mod>
 std::vector<uint64_t> ntt_poly_inv(const std::vector<uint64_t> &a, size_t n) {
   return poly_inv<>(a, n, ntt_convolve<mod>, mod_sub<mod>, mod_inv<mod>);

weilycoder/poly/elementary_func/multiply.hpp

@@ -1,17 +1,43 @@
 #ifndef WEILYCODER_POLY_ELEMENTARY_FUNC_MULTIPLY_HPP
 #define WEILYCODER_POLY_ELEMENTARY_FUNC_MULTIPLY_HPP
 
+/**
+ * @file multiply.hpp
+ * @brief Polynomial Multiplication Functions
+ */
+
 #include "../../number_theory/mod_utility.hpp"
 #include "../ntt_convolve.hpp"
 #include <vector>
 
 namespace weilycoder {
+/**
+ * @brief Multiply two polynomials using a provided multiplication function.
+ * @tparam T Coefficient type.
+ * @tparam MultiplyFunc Type of the multiplication function.
+ * @param a Coefficients of the first polynomial.
+ * @param b Coefficients of the second polynomial.
+ * @param multiply Function to multiply two polynomials.
+ * @return Coefficients of the resulting polynomial after multiplication.
+ */
 template <typename T, typename MultiplyFunc>
 std::vector<T> poly_mul(const std::vector<T> &a, const std::vector<T> &b,
                         MultiplyFunc multiply) {
   return multiply(a, b);
 }
 
+/**
+ * @brief Multiply two polynomials using a provided multiplication function,
+ *        limiting the result to degree n-1.
+ * @tparam T Coefficient type.
+ * @tparam MultiplyFunc Type of the multiplication function.
+ * @param a Coefficients of the first polynomial.
+ * @param b Coefficients of the second polynomial.
+ * @param n Maximum degree of the resulting polynomial (result size will be n).
+ * @param multiply Function to multiply two polynomials.
+ * @return Coefficients of the resulting polynomial after multiplication,
+ *         limited to degree n-1.
+ */
 template <typename T, typename MultiplyFunc>
 std::vector<T> poly_mul(const std::vector<T> &a, const std::vector<T> &b, size_t n,
                         MultiplyFunc multiply) {
@@ -21,6 +47,16 @@ std::vector<T> poly_mul(const std::vector<T> &a, const std::vector<T> &b, size_t
   return res;
 }
 
+/**
+ * @brief Multiply two polynomials using NTT under a given modulus,
+ *        limiting the result to degree n-1.
+ * @tparam mod Modulus for NTT.
+ * @param a Coefficients of the first polynomial.
+ * @param b Coefficients of the second polynomial.
+ * @param n Maximum degree of the resulting polynomial (result size will be n).
+ * @return Coefficients of the resulting polynomial after multiplication,
+ *         limited to degree n-1.
+ */
 template <uint64_t mod>
 std::vector<uint64_t> ntt_poly_mul(const std::vector<uint64_t> &a,
                                    const std::vector<uint64_t> &b, size_t n) {