HElib v2.0.0 release - documentation update

* This update includes a list of deprecated APIs and recommendations of the new APIs to use.

Author: jlhcrawford

documentation/Design_Document/HElib-design.pdf

@@ -607,6 +607,9 @@ class Ctxt
    * @brief Times equals operator with a `ZZX`.
    * @param poly Element by which to multiply.
    * @return Reference to `*this` post multiplication.
+   * @deprecated This function is deprecated in favor of a new
+   * `EncodedPtxt`-based API.\n
+   * Please use `Ctxt::operator*=(const EncodedPtxt& ptxt)` instead.
    **/
   // [[deprecated]]
   Ctxt& operator*=(const NTL::ZZX& poly);
@@ -648,34 +651,60 @@ class Ctxt
   }
 
   //! add a rational number in the form a/b, a,b are long
+  /**
+   * @deprecated This function is deprecated in favor of a newer API.
+   * Please use `Ctxt::operator+=(double ptxt)` instead.
+   **/
   // [[deprecated]]
   void addConstantCKKS(std::pair</*numerator=*/long, /*denominator=*/long>);
+  /**
+   * @deprecated This function is deprecated in favor of a newer API.
+   * Please use `Ctxt::operator+=(double ptxt)` instead.
+   **/
   // [[deprecated]]
   void addConstantCKKS(double x)
   { // FIXME: not enough precision when x is large
     addConstantCKKS(
         rationalApprox(x, /*denomBound=*/1L << getContext().getAlMod().getR()));
   }
 
+  /**
+   * @deprecated This function is deprecated in favor of a newer API.
+   * Please use `Ctxt::operator+=(const FatEncodedPtxt& ptxt)` instead.
+   **/
   // [[deprecated]]
   void addConstantCKKS(const DoubleCRT& dcrt,
                        NTL::xdouble size = NTL::xdouble(-1.0),
                        NTL::xdouble factor = NTL::xdouble(-1.0));
 
+  /**
+   * @deprecated This function is deprecated in favor of a newer API.
+   * Please use `Ctxt::operator+=(const EncodedPtxt& ptxt)` instead.
+   **/
   // [[deprecated]]
   void addConstantCKKS(const NTL::ZZX& poly,
                        NTL::xdouble size = NTL::xdouble(-1.0),
                        NTL::xdouble factor = NTL::xdouble(-1.0));
 
+  /**
+   * @deprecated This function is deprecated in favor of a newer API.
+   * Please use `Ctxt::operator+=(const PtxtArray& ptxt)` instead.
+   **/
   // [[deprecated]]
   void addConstantCKKS(const std::vector<std::complex<double>>& ptxt);
 
   /**
    * @brief Add a `CKKS` plaintext to this `Ctxt`.
    * @param ptxt Plaintext `Ptxt` object with which to add.
+   * @deprecated This function is deprecated in favor of a newer API.
+   * Please use `Ctxt::operator+=(const PtxtArray& ptxt)` instead.
    **/
   // [[deprecated]]
   void addConstantCKKS(const Ptxt<CKKS>& ptxt);
+  /**
+   * @deprecated This function is deprecated in favor of a newer API.
+   * Please use `Ctxt::operator+=(const NTL::ZZ& ptxt)` instead.
+   **/
   // [[deprecated]]
   void addConstantCKKS(const NTL::ZZ& c);
 
@@ -1061,6 +1090,10 @@ class Ctxt
   }
 
   //! multiply by a rational number or floating point
+  /**
+   * @deprecated This function is deprecated in favor of a newer API.
+   * Please use `Ctxt::operator*=(double ptxt)` instead.
+   **/
   // [[deprecated]]
   void multByConstantCKKS(double x)
   {
@@ -1082,18 +1115,30 @@ class Ctxt
       this->negate();
   }
 
+  /**
+   * @deprecated This function is deprecated in favor of a newer API.
+   * Please use `Ctxt::operator*=(double ptxt)` instead.
+   **/
   // [[deprecated]]
   void multByConstantCKKS(std::pair<long, long> num) // rational number
   {
     multByConstantCKKS(double(num.first) / num.second);
   }
 
+  /**
+   * @deprecated This function is deprecated in favor of a newer API.
+   * Please use `Ctxt::operator*=(const FatEncodedPtxt& ptxt)` instead.
+   **/
   // [[deprecated]]
   void multByConstantCKKS(const DoubleCRT& dcrt,
                           NTL::xdouble size = NTL::xdouble(-1.0),
                           NTL::xdouble factor = NTL::xdouble(-1.0),
                           double roundingErr = -1.0);
 
+  /**
+   * @deprecated This function is deprecated in favor of a newer API.
+   * Please use `Ctxt::operator*=(const EncodedPtxt& ptxt)` instead.
+   **/
   // [[deprecated]]
   void multByConstantCKKS(const NTL::ZZX& poly,
                           NTL::xdouble size = NTL::xdouble(-1.0),
@@ -1109,9 +1154,15 @@ class Ctxt
   /**
    * @brief Multiply a `CKKS` plaintext to this `Ctxt`.
    * @param ptxt Plaintext `Ptxt` object polynomial with which to multiply.
+   * @deprecated This function is deprecated in favor of a newer API.
+   * Please use `Ctxt::operator*=(const PtxtArray& ptxt)` instead.
    **/
   // [[deprecated]]
   void multByConstantCKKS(const Ptxt<CKKS>& ptxt);
+  /**
+   * @deprecated This function is deprecated in favor of a newer API.
+   * Please use `Ctxt::operator*=(const PtxtArray& ptxt)` instead.
+   **/
   // [[deprecated]]
   void multByConstantCKKS(const std::vector<std::complex<double>>& ptxt);
 
@@ -1339,7 +1390,10 @@ class Ctxt
     return 0; // just to keep the compiler happy
   }
 
-  //! @brief Returns log(noiseBound) - log(q)
+  /**
+   * @brief Returns log(noiseBound) - log(q)
+   * @deprecated This is deprecated. Please use `Ctxt::capacity()` instead.
+   **/
   // [[deprecated]] // use capacity()
   double log_of_ratio() const
   {

documentation/Design_Document/old/HElibrary.pdf renamed to documentation/Old_Document/HElibrary.pdf

@@ -1148,11 +1148,23 @@ class EncryptedArrayDerived<PA_cx> : public EncryptedArrayBase
   // VJS-FIXME: these routine have a number of issues and should
   // be deprecated in favor of the new EncodedPtxt-based routines
 
+  /**
+   * @brief Function for encoding a `double` into a `zzX`.
+   * @deprecated This routine has a number of issues and is deprecated in favor
+   * of the new `EncodedPtxt`-based routine.\n
+   * Please use `PtxtArray::encode()` instead.
+   **/
   double encode(zzX& ptxt,
                 double aSingleNumber,
                 double useThisSize = -1,
                 long precision = -1) const;
 
+  /**
+   * @brief Function for encoding a `double` into a `zzX`.
+   * @deprecated This routine has a number of issues and is deprecated in favor
+   * of the new `EncodedPtxt`-based routine.\n
+   * Please use `PtxtArray::encode()` instead.
+   **/
   template <typename PTXT>
   double encode(NTL::ZZX& ptxt,
                 const PTXT& pt,
@@ -1365,6 +1377,10 @@ class EncryptedArrayDerived<PA_cx> : public EncryptedArrayBase
     project(array, v);
   }
 
+  /**
+   * @deprecated This routine has a number of issues and is deprecated in favor
+   * of either `RandomComplex()` or `PtxtArray::random()`.
+   **/
   void random(std::vector<cx_double>& array, double rad = 1.0) const;
   void random(std::vector<double>& array, double rad = 1.0) const
   {
@@ -1990,6 +2006,12 @@ class PlaintextArrayDerived : public PlaintextArrayBase
   virtual void print(std::ostream& s) const { s << data; }
 };
 
+/**
+ * @deprecated There is a somewhat "friendlier" interface available in
+ * `PtxtArray` as it carries with it a reference to an `EncryptedArray`.
+ * It is recommended that `PlaintextArray` be deprecated in favor of
+ * `PtxtArray`.
+ **/
 class PlaintextArray
 {
 private:

documentation/Design_Document/old/HElibrary.pptx renamed to documentation/Old_Document/HElibrary.pptx

@@ -14,7 +14,8 @@
 #define HELIB_FHE_H
 /**
    @file FHE.h
-   @brief Deprecated entry point header for HElib (legacy alias of helib.h)
+   @brief Deprecated entry point header for HElib (legacy alias of `helib.h`)
+   @deprecated This header is a deprecated alias of `helib.h`.
 */
 
 #include <helib/helib.h>

documentation/Design_Document/old/he-library.bib renamed to documentation/Old_Document/he-library.bib

@@ -160,19 +160,39 @@ class PubKey
   // VJS-FIXME: these routine have a number of issues and should
   // be deprecated in favor of the new EncodedPtxt-based routines
 
+  /**
+   * @deprecated This routine has a number of issues and is deprecated in favor
+   * of the new `EncodedPtxt`-based routine.\n
+   * Please use `PtxtArray::encrypt()` instead.
+   **/
   long Encrypt(Ctxt& ciphertxt,
                const NTL::ZZX& plaintxt,
                long ptxtSpace,
                bool highNoise) const;
+  /**
+   * @deprecated This routine has a number of issues and is deprecated in favor
+   * of the new `EncodedPtxt`-based routine.\n
+   * Please use `PtxtArray::encrypt()` instead.
+   **/
   long Encrypt(Ctxt& ciphertxt,
                const zzX& plaintxt,
                long ptxtSpace,
                bool highNoise) const;
 
+  /**
+   * @deprecated This routine has a number of issues and is deprecated in favor
+   * of the new `EncodedPtxt`-based routine.\n
+   * Please use `PtxtArray::encrypt()` instead.
+   **/
   void CKKSencrypt(Ctxt& ciphertxt,
                    const NTL::ZZX& plaintxt,
                    double ptxtSize = 1.0,
                    double scaling = 0.0) const;
+  /**
+   * @deprecated This routine has a number of issues and is deprecated in favor
+   * of the new `EncodedPtxt`-based routine.\n
+   * Please use `PtxtArray::encrypt()` instead.
+   **/
   void CKKSencrypt(Ctxt& ciphertxt,
                    const zzX& plaintxt,
                    double ptxtSize = 1.0,