DOC: random doxygen improvements

include/ntru.h

@@ -108,8 +108,6 @@ string_delete(string *del_string);
  * fill with coefficients [out]
  * @param c array of polynomial coefficients, can be NULL
  * @param len size of the coefficient array, can be 0
- * @return newly allocated polynomial pointer, must be freed
- * with fmpz_poly_clear()
  */
 void
 poly_new(fmpz_poly_t new_poly,

include/ntru_keypair.h

@@ -70,7 +70,9 @@ struct keypair {
  * consisting of public and private
  * components.
  *
- * @param pair store private and public components here [out]
+ * @param pair store private and public components here (the
+ * polynomials inside the struct will be automatically
+ * initialized) [out]
  * @param f a random polynomial
  * @param g a random polynomial
  * @param params the NTRU context
@@ -111,7 +113,7 @@ export_priv_key(char const * const filename,
 /**
  * Import the public key from a file.
  *
- * @param pub where to save the public key [out]
+ * @param pub where to save the public key, must be initialized [out]
  * @param filename the file to get the public key from
  * @param params the NTRU context
  */
@@ -120,12 +122,14 @@ import_public_key(fmpz_poly_t pub,
 		char const * const filename,
 		const ntru_params *params);
 
+
 /**
  * Import the private key from a file and store him
  * along with his inverse.
  *
- * @param priv where to save the private key [out]
- * @param priv_inv where to save the inverse of the private key [out]
+ * @param priv where to save the private key, must be initialized [out]
+ * @param priv_inv where to save the inverse of the private key,
+ * must be initialized [out]
  * @param filename the file to get the private key from
  * @param params the NTRU context
  */

src/ntru_decrypt.h

@@ -40,7 +40,7 @@
  * Decryption of the given Polynom with the private key, its inverse
  * and the fitting ntru_params
  *
- * @param out_tern the resulting ternary polynom [out]
+ * @param out_tern the resulting ternary polynom, must be initialized [out]
  * @param encr_msg encrypted polynomial with maximum length of N from
  * 		the given context
  * @param priv_key the polynomial containing the private key to decrypt

src/ntru_encrypt.h

@@ -52,7 +52,7 @@
  * q = large mod
  *
  * @param out the output poly which is in the range {0, q-1}
- * (not ternary!) [out]
+ * (not ternary!), must be initialized [out]
  * @param msg_tern the message to encrypt, in ternary format
  * @param pub_key the public key
  * @param rnd the random poly (should have relatively small

src/ntru_keypair.h

@@ -67,7 +67,9 @@ struct keypair {
  * consisting of public and private
  * components.
  *
- * @param pair store private and public components here [out]
+ * @param pair store private and public components here (the
+ * polynomials inside the struct will be automatically
+ * initialized) [out]
  * @param f a random polynomial
  * @param g a random polynomial
  * @param params the NTRU context
@@ -108,7 +110,7 @@ export_priv_key(char const * const filename,
 /**
  * Import the public key from a file.
  *
- * @param pub where to save the public key [out]
+ * @param pub where to save the public key, must be initialized [out]
  * @param filename the file to get the public key from
  * @param params the NTRU context
  */
@@ -121,8 +123,9 @@ import_public_key(fmpz_poly_t pub,
  * Import the private key from a file and store him
  * along with his inverse.
  *
- * @param priv where to save the private key [out]
- * @param priv_inv where to save the inverse of the private key [out]
+ * @param priv where to save the private key, must be initialized [out]
+ * @param priv_inv where to save the inverse of the private key,
+ * must be initialized [out]
  * @param filename the file to get the private key from
  * @param params the NTRU context
  */

src/ntru_poly.c

@@ -47,7 +47,7 @@
  * Find the inverse polynomial modulo a power of 2,
  * which is q.
  *
- * @param Fq polynomial [out]
+ * @param Fq polynomial, must be initialized [out]
  * @param a polynomial to invert
  * @param params NTRU parameters
  */

src/ntru_poly.h

@@ -60,8 +60,6 @@ fmpz_cmp_si_n(const fmpz_t f, slong g);
  * fill with coefficients [out]
  * @param c array of polynomial coefficients, can be NULL
  * @param len size of the coefficient array, can be 0
- * @return newly allocated polynomial pointer, must be freed
- * with fmpz_poly_clear()
  */
 void
 poly_new(fmpz_poly_t new_poly,
@@ -169,7 +167,7 @@ fmpz_add_n(fmpz_t f, const fmpz_t g, const fmpz_t h);
  * Starmultiplication, as follows:
  * c = a * b mod (x^N − 1)
  *
- * @param c polynom [out]
+ * @param c polynom, must be initialized [out]
  * @param a polynom to multiply (can be the same as c)
  * @param b polynom to multiply
  * @param params NTRU parameters
@@ -189,7 +187,7 @@ poly_starmultiply(fmpz_poly_t c,
  * See NTRU Cryptosystems Tech Report #014 "Almost Inverses
  * and Fast NTRU Key Creation."
  *
- * @param Fq polynomial [out]
+ * @param Fq polynomial, must be initialized [out]
  * @param a polynomial to invert (is allowed to be the same as param Fq)
  * @param params NTRU parameters
  * @return true if invertible, false if not
@@ -204,7 +202,7 @@ poly_inverse_poly_q(fmpz_poly_t Fq,
  * See NTRU Cryptosystems Tech Report #014 "Almost Inverses
  * and Fast NTRU Key Creation."
  *
- * @param Fp polynomial [out]
+ * @param Fp polynomial, must be initialized [out]
  * @param a polynomial to invert
  * @param params NTRU parameters
  * @return true if invertible, false if not