DOC: add brief/file comments

src/context.h

@@ -19,6 +19,12 @@
  * MA  02110-1301  USA
  */
 
+/**
+ * @file context.h
+ * This file defines the ntru_context
+ * and related data types.
+ * @brief NTRU context types
+ */
 
 #ifndef NTRU_CONTEXT_H
 #define NTRU_CONTEXT_H

src/decrypt.c

@@ -19,6 +19,13 @@
  * MA  02110-1301  USA
  */
 
+/**
+ * @file decrypt.c
+ * This file handles the NTRU decryption
+ * algorithm.
+ * @brief NTRU decryption
+ */
+
 #include "decrypt.h"
 
 #include <fmpz_poly.h>

src/decrypt.h

@@ -19,6 +19,12 @@
  * MA  02110-1301  USA
  */
 
+/**
+ * @file decrypt.h
+ * Header for the external API of decrypt.c.
+ * @brief header for decrypt.c
+ */
+
 #ifndef NTRU_DECRYPT_H
 #define NTRU_DECRYPT_H
 

src/encrypt.c

@@ -19,6 +19,13 @@
  * MA  02110-1301  USA
  */
 
+/**
+ * @file encrypt.c
+ * This file handles the NTRU encryption
+ * algorithm.
+ * @brief NTRU encryption
+ */
+
 #include "encrypt.h"
 
 #include <fmpz_poly.h>

src/encrypt.h

@@ -19,6 +19,12 @@
  * MA  02110-1301  USA
  */
 
+/**
+ * @file encrypt.h
+ * Header for the internal API of encrypt.c.
+ * @brief header for encrypt.c
+ */
+
 #ifndef PQC_ENCRYPT_H
 #define PQC_ENCRYPT_H
 

src/err.h

@@ -19,6 +19,12 @@
  * MA  02110-1301  USA
  */
 
+/**
+ * @file err.h
+ * This file provides error macros
+ * and functions for the NTRU cryptosystem.
+ * @brief error handling
+ */
 
 #ifndef NTRU_ERR_H
 #define NTRU_ERR_H

src/keypair.c

@@ -19,6 +19,13 @@
  * MA  02110-1301  USA
  */
 
+/**
+ * @file keypair.c
+ * This file handles the creation of the
+ * key pair and possibly common operations on them.
+ * @brief key creation and operations
+ */
+
 #include "context.h"
 #include "keypair.h"
 #include "poly.h"
@@ -29,6 +36,16 @@
 #include <stdbool.h>
 
 
+/**
+ * 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,

src/keypair.h

@@ -19,6 +19,12 @@
  * MA  02110-1301  USA
  */
 
+/**
+ * @file keypair.h
+ * Header for internal API of keypair.c.
+ * @brief header for keypair.c
+ */
+
 #ifndef NTRU_KEYPAIR_H
 #define NTRU_KEYPAIR_H
 

src/mem.c

@@ -19,6 +19,13 @@
  * MA  02110-1301  USA
  */
 
+/**
+ * @file mem.c
+ * This file provides functions for
+ * memory management.
+ * @brief memory management
+ */
+
 #include "mem.h"
 
 #include <stdio.h>

src/mem.h

@@ -19,6 +19,12 @@
  * MA  02110-1301  USA
  */
 
+/**
+ * @file mem.h
+ * Header for the internal API of mem.c.
+ * @brief header for mem.c
+ */
+
 #ifndef NTRU_MEM_H
 #define NTRU_MEM_H
 

src/poly.c

@@ -19,6 +19,14 @@
  * MA  02110-1301  USA
  */
 
+/**
+ * @file poly.c
+ * This files purpose is to handle polynomials
+ * in general, allowing modification, arithmetic
+ * and common algorithms like inverting them.
+ * @brief operations on polynomials
+ */
+
 #include "context.h"
 #include "err.h"
 #include "mem.h"

src/poly.h

@@ -19,6 +19,11 @@
  * MA  02110-1301  USA
  */
 
+/**
+ * @file poly.h
+ * Header for the internal API of poly.c.
+ * @brief header for poly.c
+ */
 
 #ifndef NTRU_POLY_H
 #define NTRU_POLY_H