ALL: improve readability

src/ascii_poly.c

@@ -40,13 +40,6 @@
 #include <fmpz.h>
 
 
-/*
- * static function declaration
- */
-static char *get_int_to_bin_str(uint8_t value);
-static char *get_bin_arr_to_ascii(char *binary_rep);
-
-
 /**
  * Convert an integer to it's binary representation
  * as a string and return it.
@@ -54,7 +47,25 @@ static char *get_bin_arr_to_ascii(char *binary_rep);
  * @param value the integer to convert
  * @return the binary representation as a newly allocated string
  */
-static char *get_int_to_bin_str(uint8_t value)
+static char *
+get_int_to_bin_str(uint8_t value);
+
+/**
+ * Converts a binary representation of multiple concatenated
+ * integers to the corresponding array of ascii chars, which
+ * is NULL-terminated.
+ *
+ * @param binary_rep the binary representation of multiple
+ * integers concatenated
+ * @return NULL-terminated array of corresponding ascii-chars,
+ * newly allocated
+ */
+static char *
+get_bin_arr_to_ascii(char *binary_rep);
+
+
+static char *
+get_int_to_bin_str(uint8_t value)
 {
     int i;
 	const size_t bin_string_size = ASCII_BITS + 1;
@@ -70,17 +81,8 @@ static char *get_int_to_bin_str(uint8_t value)
 	return bin_string;
 }
 
-/**
+static char *
- * Converts a binary representation of multiple concatenated
+get_bin_arr_to_ascii(char *binary_rep)
- * integers to the corresponding array of ascii chars, which
- * is NULL-terminated.
- *
- * @param binary_rep the binary representation of multiple
- * integers concatenated
- * @return NULL-terminated array of corresponding ascii-chars,
- * newly allocated
- */
-static char *get_bin_arr_to_ascii(char *binary_rep)
 {
 	const size_t int_arr_size = strlen(binary_rep) / ASCII_BITS;
 	uint8_t int_arr[int_arr_size];
@@ -109,14 +111,8 @@ static char *get_bin_arr_to_ascii(char *binary_rep)
 	return int_string;
 }
 
-/**
+fmpz_poly_t **
- * Convert an ascii string to an array of polyomials.
+ascii_to_poly(char *to_poly, ntru_context *ctx)
- *
- * @param to_poly the string to get into polynomial format
- * @param ctx the NTRUEncrypt context
- * @return newly allocated array of polynomials
- */
-fmpz_poly_t **ascii_to_poly(char *to_poly, ntru_context *ctx)
 {
 	uint32_t i = 0,
 			 polyc = 0;
@@ -159,14 +155,8 @@ fmpz_poly_t **ascii_to_poly(char *to_poly, ntru_context *ctx)
 	return poly_array;
 }
 
-/**
+char *
- * Convert an array of polynomials back to a real string.
+poly_to_ascii(fmpz_poly_t **poly_array, ntru_context *ctx)
- *
- * @param poly_array the array of polynomials
- * @param ctx the NTRUEncrypt context
- * @return the real string
- */
-char *poly_to_ascii(fmpz_poly_t **poly_array, ntru_context *ctx)
 {
 	fmpz_poly_t *ascii_poly;
 	char *binary_rep = NULL;

src/ascii_poly.h

@@ -35,8 +35,25 @@
 #include <fmpz.h>
 
 
-fmpz_poly_t **ascii_to_poly(char *to_poly, ntru_context *ctx);
+/**
-char *poly_to_ascii(fmpz_poly_t **poly_array, ntru_context *ctx);
+ * Convert an ascii string to an array of polyomials.
+ *
+ * @param to_poly the string to get into polynomial format
+ * @param ctx the NTRUEncrypt context
+ * @return newly allocated array of polynomials
+ */
+fmpz_poly_t **
+ascii_to_poly(char *to_poly, ntru_context *ctx);
+
+/**
+ * Convert an array of polynomials back to a real string.
+ *
+ * @param poly_array the array of polynomials
+ * @param ctx the NTRUEncrypt context
+ * @return the real string
+ */
+char *
+poly_to_ascii(fmpz_poly_t **poly_array, ntru_context *ctx);
 
 
 #endif /* NTRU_ASCII_POLY_H_ */

src/decrypt.c

@@ -32,19 +32,8 @@
 #include <fmpz.h>
 
 
-/**
+void
- * Decryption of the given Polynom with the private key, its inverse
+ntru_decrypt_poly(
- * and the fitting ntru_context
- *
- * @param encr_msg encrypted polynom with maximum length of N from
- * 		the given context
- * @param priv_key the polynom containing the private key to decrypt
- * 		the message
- * @param priv_key_inv the inverse polynome to the private key
- * @param out the result polynom is written in here [out]
- * @param ctx the ntru_context
- */
-void ntru_decrypt_poly(
 		fmpz_poly_t encr_msg,
 		fmpz_poly_t priv_key,
 		fmpz_poly_t priv_key_inv,

src/decrypt.h

@@ -35,7 +35,20 @@
 #include <fmpz.h>
 
 
-void ntru_decrypt_poly(
+/**
+ * Decryption of the given Polynom with the private key, its inverse
+ * and the fitting ntru_context
+ *
+ * @param encr_msg encrypted polynom with maximum length of N from
+ * 		the given context
+ * @param priv_key the polynom containing the private key to decrypt
+ * 		the message
+ * @param priv_key_inv the inverse polynome to the private key
+ * @param out the result polynom is written in here [out]
+ * @param ctx the ntru_context
+ */
+void
+ntru_decrypt_poly(
 		fmpz_poly_t encr_msg,
 		fmpz_poly_t priv_key,
 		fmpz_poly_t priv_key_inv,

src/encrypt.c

@@ -32,23 +32,8 @@
 #include <fmpz.h>
 
 
-/**
+void
- * encrypt the msg, using the math:
+ntru_encrypt_poly(
- * e = (h ∗ r) + m (mod q)
- *
- * e = the encrypted poly
- * h = the public key
- * r = the random poly
- * m = the message poly
- * q = large mod
- *
- * @param msg pb_poly* 		the message to encrypt
- * @param pub_key pb_poly* 	the public key
- * @param rnd pb_poly*   	the random poly
- * @param out pb_poly* 		the output poly [out]
- * @param ctx ntru_context* the ntru context
- */
-void ntru_encrypt_poly(
 		fmpz_poly_t msg,
 		fmpz_poly_t pub_key,
 		fmpz_poly_t rnd,

src/encrypt.h

@@ -36,7 +36,24 @@
 #include <fmpz.h>
 
 
-void ntru_encrypt_poly(
+/**
+ * encrypt the msg, using the math:
+ * e = (h ∗ r) + m (mod q)
+ *
+ * e = the encrypted poly
+ * h = the public key
+ * r = the random poly
+ * m = the message poly
+ * q = large mod
+ *
+ * @param msg pb_poly* 		the message to encrypt
+ * @param pub_key pb_poly* 	the public key
+ * @param rnd pb_poly*   	the random poly
+ * @param out pb_poly* 		the output poly [out]
+ * @param ctx ntru_context* the ntru context
+ */
+void
+ntru_encrypt_poly(
 		fmpz_poly_t msg,
 		fmpz_poly_t pub_key,
 		fmpz_poly_t rnd,

src/keypair.c

@@ -36,17 +36,8 @@
 #include <stdbool.h>
 
 
-/**
+bool
- * Creates an NTRU key pair,
+ntru_create_keypair(
- * consisting of public and private
- * components.
- *
- * @param f a random polynomial
- * @param g a random polynomial
- * @param pair store private and public components here [out]
- * @param ctx the NTRU context
- */
-bool ntru_create_keypair(
 		fmpz_poly_t f,
 		fmpz_poly_t g,
 		keypair *pair,
@@ -91,14 +82,8 @@ cleanup:
 	return retval;
 }
 
-/**
+void
- * Used to free the inner structure
+ntru_delete_keypair(keypair *pair)
- * of a keypair. This will not call free()
- * on the pair itself.
- *
- * @param pair the pair to free the inner structure of
- */
-void ntru_delete_keypair(keypair *pair)
 {
 	fmpz_poly_clear(pair->priv_inv);
 	fmpz_poly_clear(pair->priv);

src/keypair.h

@@ -62,13 +62,32 @@ struct keypair {
 };
 
 
-bool ntru_create_keypair(
+/**
+ * Creates an NTRU key pair,
+ * consisting of public and private
+ * components.
+ *
+ * @param f a random polynomial
+ * @param g a random polynomial
+ * @param pair store private and public components here [out]
+ * @param ctx the NTRU context
+ */
+bool
+ntru_create_keypair(
 		fmpz_poly_t f,
 		fmpz_poly_t g,
 		keypair *pair,
 		ntru_context *ctx);
 
-void ntru_delete_keypair(keypair *pair);
+/**
+ * Used to free the inner structure
+ * of a keypair. This will not call free()
+ * on the pair itself.
+ *
+ * @param pair the pair to free the inner structure of
+ */
+void
+ntru_delete_keypair(keypair *pair);
 
 
 #endif /* NTRU_KEYPAIR_H */

src/mem.c

@@ -32,14 +32,8 @@
 #include <stdlib.h>
 
 
-/**
+void *
- * Allocate memory of size and return
+ntru_malloc(size_t size)
- * a void pointer.
- *
- * @param size of the memory to allocate in bytes
- * @return void pointer to the beginning of the allocated memory block
- */
-void *ntru_malloc(size_t size)
 {
 	void *ptr;
 
@@ -54,15 +48,8 @@ void *ntru_malloc(size_t size)
 	return ptr;
 }
 
-/**
+void *
- * Allocate memory of size and return
+ntru_calloc(size_t nmemb, size_t size)
- * a void pointer. The memory is zeroed.
- *
- * @param nmemb amount of blocks to allocate
- * @param size of the memory blocks to allocate in bytes
- * @return void pointer to the beginning of the allocated memory block
- */
-void *ntru_calloc(size_t nmemb, size_t size)
 {
 	void *ptr;
 

src/mem.h

@@ -47,8 +47,26 @@
 }
 
 
-void *ntru_malloc(size_t size);
+/**
-void *ntru_calloc(size_t nmemb, size_t size);
+ * Allocate memory of size and return
+ * a void pointer.
+ *
+ * @param size of the memory to allocate in bytes
+ * @return void pointer to the beginning of the allocated memory block
+ */
+void *
+ntru_malloc(size_t size);
+
+/**
+ * Allocate memory of size and return
+ * a void pointer. The memory is zeroed.
+ *
+ * @param nmemb amount of blocks to allocate
+ * @param size of the memory blocks to allocate in bytes
+ * @return void pointer to the beginning of the allocated memory block
+ */
+void *
+ntru_calloc(size_t nmemb, size_t size);
 
 
 #endif /* NTRU_MEM_H */

src/poly.c

@@ -43,14 +43,6 @@
 #include <fmpz.h>
 
 
-/*
- * static declarations
- */
-static void poly_mod2_to_modq(fmpz_poly_t a,
-		fmpz_poly_t Fq,
-		ntru_context *ctx);
-
-
 /**
  * Find the inverse polynomial modulo a power of 2,
  * which is q.
@@ -59,7 +51,14 @@ static void poly_mod2_to_modq(fmpz_poly_t a,
  * @param Fq polynomial [out]
  * @param ctx NTRU context
  */
-static void poly_mod2_to_modq(fmpz_poly_t a,
+static
+void poly_mod2_to_modq(fmpz_poly_t a,
+		fmpz_poly_t Fq,
+		ntru_context *ctx);
+
+
+static void
+poly_mod2_to_modq(fmpz_poly_t a,
 		fmpz_poly_t Fq,
 		ntru_context *ctx)
 {
@@ -86,20 +85,8 @@ static void poly_mod2_to_modq(fmpz_poly_t a,
 
 }
 
-/**
+void
- * Initializes and builds a polynomial with the
+poly_new(fmpz_poly_t new_poly,
- * coefficient values of c[] of size len within NTRU
- * context ctx and returns a newly allocated polynomial.
- * For an empty polynom, both parameters can be NULL/0.
- *
- * @param new_poly the polynomial to initialize and
- * fill with coefficients
- * @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,
 		int const * const c,
 		const size_t len)
 {
@@ -109,26 +96,14 @@ void poly_new(fmpz_poly_t new_poly,
 		fmpz_poly_set_coeff_si(new_poly, i, c[i]);
 }
 
-/**
+void
- * This deletes the internal structure of a polynomial,
+poly_delete(fmpz_poly_t poly)
- * and frees the pointer.
- *
- * @param poly the polynomial to delete
- */
-void poly_delete(fmpz_poly_t poly)
 {
 	fmpz_poly_clear(poly);
 }
 
-/**
+void
- * Delete the internal structure of a polynomial
+poly_delete_array(fmpz_poly_t **poly_array)
- * array which must be NULL terminated. It is expected
- * that poly_array is not on the stack and was obtained
- * by a function like ascii_to_poly().
- *
- * @param poly_array the polynomial array
- */
-void poly_delete_array(fmpz_poly_t **poly_array)
 {
 	uint32_t i = 0;
 
@@ -140,15 +115,8 @@ void poly_delete_array(fmpz_poly_t **poly_array)
 	free(poly_array);
 }
 
-/**
+void
- * This deletes the internal structure of all polynomials,
+poly_delete_all(fmpz_poly_t poly, ...)
- * and frees the pointers.
- * You must call this with NULL as last argument!
- *
- * @param poly the polynomial to delete
- * @param ... follow up polynomials
- */
-void poly_delete_all(fmpz_poly_t poly, ...)
 {
 	fmpz_poly_struct *next_poly;
 	va_list args;
@@ -162,19 +130,8 @@ void poly_delete_all(fmpz_poly_t poly, ...)
 	va_end(args);
 }
 
-/**
+void
- * Calls fmpz_poly_get_nmod_poly() and
+fmpz_poly_mod_unsigned(fmpz_poly_t a,
- * fmpz_poly_set_nmod_poly_unsigned() in a row,
- * so we don't have to deal with the intermediate
- * nmod_poly_t type if we don't need it.
- *
- * This also normalises the coefficients to the interval
- * 0 <= r < m.
- *
- * @param a the polynom to apply the modulus to
- * @param mod the modulus
- */
-void fmpz_poly_mod_unsigned(fmpz_poly_t a,
 		uint32_t mod)
 {
 	nmod_poly_t nmod_tmp;
@@ -187,19 +144,8 @@ void fmpz_poly_mod_unsigned(fmpz_poly_t a,
 	nmod_poly_clear(nmod_tmp);
 }
 
-/**
+void
- * Calls fmpz_poly_get_nmod_poly() and
+fmpz_poly_mod(fmpz_poly_t a,
- * fmpz_poly_set_nmod_poly() in a row,
- * so we don't have to deal with the intermediate
- * nmod_poly_t type if we don't need it.
- *
- * This also normalises the coefficients to the interval
- * -m/2 <= r < m/2.
- *
- * @param a the polynom to apply the modulus to
- * @param mod the modulus
- */
-void fmpz_poly_mod(fmpz_poly_t a,
 		uint32_t mod)
 {
 	nmod_poly_t nmod_tmp;
@@ -212,16 +158,8 @@ void fmpz_poly_mod(fmpz_poly_t a,
 	nmod_poly_clear(nmod_tmp);
 }
 
-/**
+void
- * The same as fmpz_poly_set_coeff_fmpz() except that it
+fmpz_poly_set_coeff_fmpz_n(fmpz_poly_t poly, slong n,
- * will take care of null-pointer coefficients and use
- * fmpz_poly_set_coeff_si() in that case.
- *
- * @param poly the polynom we want to change a coefficient of
- * @param n the coefficient we want to set
- * @param x the value to assign to the coefficient
- */
-void fmpz_poly_set_coeff_fmpz_n(fmpz_poly_t poly, slong n,
 		const fmpz_t x)
 {
 	if (x)
@@ -230,15 +168,8 @@ void fmpz_poly_set_coeff_fmpz_n(fmpz_poly_t poly, slong n,
 		fmpz_poly_set_coeff_si(poly, n, 0);
 }
 
-/**
+int
- * Wrapper around fmpz_invmod() where we convert
+fmpz_invmod_ui(fmpz_t f, const fmpz_t g, uint32_t mod)
- * mod to an fmpz_t implicitly.
- *
- * @param f result [out]
- * @param g the inverse
- * @param mod the modulo
- */
-int fmpz_invmod_ui(fmpz_t f, const fmpz_t g, uint32_t mod)
 {
 	fmpz_t modulus;
 
@@ -247,11 +178,8 @@ int fmpz_invmod_ui(fmpz_t f, const fmpz_t g, uint32_t mod)
 	return fmpz_invmod(f, g, modulus);
 }
 
-/**
+void
- * The same as fmpz_add() except that it handles NULL
+fmpz_add_n(fmpz_t f, const fmpz_t g, const fmpz_t h)
- * pointer for g and h.
- */
-void fmpz_add_n(fmpz_t f, const fmpz_t g, const fmpz_t h)
 {
 	if (!g && !h) {
 		fmpz_zero(f);
@@ -265,17 +193,8 @@ void fmpz_add_n(fmpz_t f, const fmpz_t g, const fmpz_t h)
 	}
 }
 
-/**
+void
- * Starmultiplication, as follows:
+poly_starmultiply(fmpz_poly_t a,
- * c = a * b mod (x^N − 1)
- *
- * @param a polynom to multiply (can be the same as c)
- * @param b polynom to multiply
- * @param c polynom [out]
- * @param ctx NTRU context
- * @param modulus whether we use p or q
- */
-void poly_starmultiply(fmpz_poly_t a,
 		fmpz_poly_t b,
 		fmpz_poly_t c,
 		ntru_context *ctx,
@@ -330,19 +249,8 @@ void poly_starmultiply(fmpz_poly_t a,
 	fmpz_poly_clear(a_tmp);
 }
 
-/**
+bool
- * Compute the inverse of a polynomial in modulo a power of 2,
+poly_inverse_poly_q(fmpz_poly_t a,
- * which is q. This is based off the pseudo-code for "Inversion
- * in (Z/2Z)[X](X^N - 1)" and "Inversion in (Z/p^r Z)[X](X^N - 1)".
- * See NTRU Cryptosystems Tech Report #014 "Almost Inverses
- * and Fast NTRU Key Creation."
- *
- * @param a polynomial to invert (is allowed to be the same as param Fq)
- * @param Fq polynomial [out]
- * @param ctx NTRU context
- * @return true if invertible, false if not
- */
-bool poly_inverse_poly_q(fmpz_poly_t a,
 		fmpz_poly_t Fq,
 		ntru_context *ctx)
 {
@@ -456,16 +364,8 @@ cleanup:
 	return retval;
 }
 
-/**
+bool
- * Compute the inverse of a polynomial in (Z/pZ)[X]/(X^N - 1).
+poly_inverse_poly_p(fmpz_poly_t a,
- * See NTRU Cryptosystems Tech Report #014 "Almost Inverses
- * and Fast NTRU Key Creation."
- *
- * @param a polynomial to invert
- * @param Fp polynomial [out]
- * @param ctx NTRU context
- */
-bool poly_inverse_poly_p(fmpz_poly_t a,
 		fmpz_poly_t Fp,
 		ntru_context *ctx)
 {
@@ -632,24 +532,15 @@ cleanup:
 	return retval;
 }
 
-/**
+void
- * Draws a polynomial to stdout.
+poly_draw(fmpz_poly_t poly)
- *
- * @param poly draw this
- */
-void poly_draw(fmpz_poly_t poly)
 {
 	fmpz_poly_print(poly);
 	flint_printf("\n");
 }
 
-/**
+void
- * Draws a polynomial to stdout,
+poly_draw_pretty(fmpz_poly_t poly)
- * in pretty format.
- *
- * @param poly draw this
- */
-void poly_draw_pretty(fmpz_poly_t poly)
 {
 	fmpz_poly_print_pretty(poly, "x");
 	flint_printf("\n");

src/poly.h

@@ -39,49 +39,185 @@
 #include <fmpz_poly.h>
 
 
-void poly_new(fmpz_poly_t new_poly,
+/**
+ * Initializes and builds a polynomial with the
+ * coefficient values of c[] of size len within NTRU
+ * context ctx and returns a newly allocated polynomial.
+ * For an empty polynom, both parameters can be NULL/0.
+ *
+ * @param new_poly the polynomial to initialize and
+ * fill with coefficients
+ * @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,
 		int const * const c,
 		const size_t len);
 
-void poly_delete(fmpz_poly_t poly);
+/**
+ * This deletes the internal structure of a polynomial,
+ * and frees the pointer.
+ *
+ * @param poly the polynomial to delete
+ */
+void
+poly_delete(fmpz_poly_t poly);
 
-void poly_delete_array(fmpz_poly_t **poly_array);
+/**
+ * Delete the internal structure of a polynomial
+ * array which must be NULL terminated. It is expected
+ * that poly_array is not on the stack and was obtained
+ * by a function like ascii_to_poly().
+ *
+ * @param poly_array the polynomial array
+ */
+void
+poly_delete_array(fmpz_poly_t **poly_array);
 
-void poly_delete_all(fmpz_poly_t poly, ...);
+/**
+ * This deletes the internal structure of all polynomials,
+ * and frees the pointers.
+ * You must call this with NULL as last argument!
+ *
+ * @param poly the polynomial to delete
+ * @param ... follow up polynomials
+ */
+void
+poly_delete_all(fmpz_poly_t poly, ...);
 
-void fmpz_poly_mod_unsigned(fmpz_poly_t a,
+/**
+ * Calls fmpz_poly_get_nmod_poly() and
+ * fmpz_poly_set_nmod_poly_unsigned() in a row,
+ * so we don't have to deal with the intermediate
+ * nmod_poly_t type if we don't need it.
+ *
+ * This also normalises the coefficients to the interval
+ * 0 <= r < m.
+ *
+ * @param a the polynom to apply the modulus to
+ * @param mod the modulus
+ */
+void
+fmpz_poly_mod_unsigned(fmpz_poly_t a,
 		uint32_t mod);
 
-void fmpz_poly_mod(fmpz_poly_t a,
+/**
+ * Calls fmpz_poly_get_nmod_poly() and
+ * fmpz_poly_set_nmod_poly() in a row,
+ * so we don't have to deal with the intermediate
+ * nmod_poly_t type if we don't need it.
+ *
+ * This also normalises the coefficients to the interval
+ * -m/2 <= r < m/2.
+ *
+ * @param a the polynom to apply the modulus to
+ * @param mod the modulus
+ */
+void
+fmpz_poly_mod(fmpz_poly_t a,
 		uint32_t mod);
 
-void fmpz_poly_set_coeff_fmpz_n(fmpz_poly_t poly,
+/**
+ * The same as fmpz_poly_set_coeff_fmpz() except that it
+ * will take care of null-pointer coefficients and use
+ * fmpz_poly_set_coeff_si() in that case.
+ *
+ * @param poly the polynom we want to change a coefficient of
+ * @param n the coefficient we want to set
+ * @param x the value to assign to the coefficient
+ */
+void
+fmpz_poly_set_coeff_fmpz_n(fmpz_poly_t poly,
 		slong n,
 		const fmpz_t x);
 
-int fmpz_invmod_ui(fmpz_t f,
+/**
+ * Wrapper around fmpz_invmod() where we convert
+ * mod to an fmpz_t implicitly.
+ *
+ * @param f result [out]
+ * @param g the inverse
+ * @param mod the modulo
+ */
+int
+fmpz_invmod_ui(fmpz_t f,
 		const fmpz_t g,
 		uint32_t mod);
 
-void fmpz_add_n(fmpz_t f, const fmpz_t g, const fmpz_t h);
+/**
+ * The same as fmpz_add() except that it handles NULL
+ * pointer for g and h.
+ */
+void
+fmpz_add_n(fmpz_t f, const fmpz_t g, const fmpz_t h);
 
-void poly_starmultiply(fmpz_poly_t a,
+/**
+ * Starmultiplication, as follows:
+ * c = a * b mod (x^N − 1)
+ *
+ * @param a polynom to multiply (can be the same as c)
+ * @param b polynom to multiply
+ * @param c polynom [out]
+ * @param ctx NTRU context
+ * @param modulus whether we use p or q
+ */
+void
+poly_starmultiply(fmpz_poly_t a,
 		fmpz_poly_t b,
 		fmpz_poly_t c,
 		ntru_context *ctx,
 		uint32_t modulus);
 
-bool poly_inverse_poly_q(fmpz_poly_t a,
+/**
+ * Compute the inverse of a polynomial in modulo a power of 2,
+ * which is q. This is based off the pseudo-code for "Inversion
+ * in (Z/2Z)[X](X^N - 1)" and "Inversion in (Z/p^r Z)[X](X^N - 1)".
+ * See NTRU Cryptosystems Tech Report #014 "Almost Inverses
+ * and Fast NTRU Key Creation."
+ *
+ * @param a polynomial to invert (is allowed to be the same as param Fq)
+ * @param Fq polynomial [out]
+ * @param ctx NTRU context
+ * @return true if invertible, false if not
+ */
+bool
+poly_inverse_poly_q(fmpz_poly_t a,
 		fmpz_poly_t Fq,
 		ntru_context *ctx);
 
-bool poly_inverse_poly_p(fmpz_poly_t a,
+/**
+ * Compute the inverse of a polynomial in (Z/pZ)[X]/(X^N - 1).
+ * See NTRU Cryptosystems Tech Report #014 "Almost Inverses
+ * and Fast NTRU Key Creation."
+ *
+ * @param a polynomial to invert
+ * @param Fp polynomial [out]
+ * @param ctx NTRU context
+ */
+bool
+poly_inverse_poly_p(fmpz_poly_t a,
 		fmpz_poly_t Fp,
 		ntru_context *ctx);
 
-void poly_draw(fmpz_poly_t poly);
+/**
+ * Draws a polynomial to stdout.
+ *
+ * @param poly draw this
+ */
+void
+poly_draw(fmpz_poly_t poly);
 
-void poly_draw_pretty(fmpz_poly_t poly);
+/**
+ * Draws a polynomial to stdout,
+ * in pretty format.
+ *
+ * @param poly draw this
+ */
+void
+poly_draw_pretty(fmpz_poly_t poly);
 
 
 #endif /* NTRU_POLY_H */