- code documentation cleaned
authorJan Hutter <jhutter@hsr.ch>
Fri, 25 Nov 2005 08:22:27 +0000 (08:22 -0000)
committerJan Hutter <jhutter@hsr.ch>
Fri, 25 Nov 2005 08:22:27 +0000 (08:22 -0000)
Source/charon/utils/gmp_helper.c
Source/charon/utils/gmp_helper.h

index f0454a0..998e94b 100644 (file)
@@ -1,7 +1,7 @@
 /**
  * @file gmp_helper.c
  * 
- * @brief Class with helper functions for gmp operations
+ * @brief Implementation of gmp_helper_t.
  * 
  */
 
 #include <utils/randomizer.h>
 
 /**
- * Number of times the probabilistic primality test is applied
+ * Number of times the probabilistic primality test is applied.
  */
 #define PRIMECHECK_ROUNDS 30
 
+
 typedef struct private_gmp_helper_t private_gmp_helper_t;
 
 /**
@@ -40,7 +41,7 @@ typedef struct private_gmp_helper_t private_gmp_helper_t;
  */
 struct private_gmp_helper_t {
        /**
-        * public gmp_helper_t interface
+        * Public gmp_helper_t interface.
         */
        gmp_helper_t public;
 
@@ -48,8 +49,7 @@ struct private_gmp_helper_t {
 
 
 /**
- * Implements private_gmp_helper_t's chunk_to_mpz function.
- * See #private_gmp_helper_t.chunk_to_mpz for description.
+ * Implementation of gmp_helper_t.chunk_to_mpz.
  */
 static void chunk_to_mpz(private_gmp_helper_t *this, mpz_t *mpz_value, chunk_t data)
 {
@@ -65,8 +65,7 @@ static void chunk_to_mpz(private_gmp_helper_t *this, mpz_t *mpz_value, chunk_t d
 }
 
 /**
- * Implements private_gmp_helper_t's mpz_to_chunk function.
- * See #private_gmp_helper_t.mpz_to_chunk for description.
+ * Implementation of gmp_helper_t.mpz_to_chunk.
  */
 static status_t mpz_to_chunk (private_gmp_helper_t *this,mpz_t *mpz_value, chunk_t *data,size_t bytes)
 {
@@ -115,8 +114,7 @@ static status_t mpz_to_chunk (private_gmp_helper_t *this,mpz_t *mpz_value, chunk
 }
 
 /**
- * Implements gmp_helper_t's init_prime function.
- * See #gmp_helper_t.init_prime for description.
+ * Implementation of gmp_helper_t.init_prime.
  */
 static status_t init_prime (private_gmp_helper_t *this, mpz_t *prime, int bytes)
 {
@@ -140,11 +138,7 @@ static status_t init_prime (private_gmp_helper_t *this, mpz_t *prime, int bytes)
        
        /* not needed anymore */
        randomizer->destroy(randomizer);
-       if (status != SUCCESS)
-       {
-               return status;
-       }
-               
+               
        /* convert chunk to mpz value */
        this->public.chunk_to_mpz(&(this->public),prime, random_bytes);
 
@@ -158,7 +152,9 @@ static status_t init_prime (private_gmp_helper_t *this, mpz_t *prime, int bytes)
        return SUCCESS;
 }
 
-
+/**
+ * Implementation of gmp_helper_t.init_prime_fast.
+ */
 static status_t init_prime_fast (private_gmp_helper_t *this, mpz_t *prime, int bytes){
        randomizer_t *randomizer;
     chunk_t random_bytes;
@@ -182,10 +178,6 @@ static status_t init_prime_fast (private_gmp_helper_t *this, mpz_t *prime, int b
        random_bytes.ptr[0] = random_bytes.ptr[0] | 0x80;
        /* not needed anymore */
        randomizer->destroy(randomizer);
-       if (status != SUCCESS)
-       {
-               return status;
-       }
 
        /* convert chunk to mpz value */
        this->public.chunk_to_mpz(&(this->public),prime, random_bytes);
@@ -214,7 +206,7 @@ static status_t init_prime_fast (private_gmp_helper_t *this, mpz_t *prime, int b
     length = mpz_sizeinbase(*prime, 2);
 
 
-    /* check bit length of primee */
+    /* check bit length of prime */
        if ((length < (bytes * 8)) || (length > ((bytes * 8) + 1)))
        {
                return FAILED;
@@ -235,8 +227,7 @@ static status_t init_prime_fast (private_gmp_helper_t *this, mpz_t *prime, int b
 
 
 /**
- * Implements gmp_helper_t's destroy function.
- * See #gmp_helper_t.destroy for description.
+ * Implementation of gmp_helper_t.destroy.
  */
 static status_t destroy(private_gmp_helper_t *this)
 {
index 92f7d2b..1987658 100644 (file)
@@ -1,7 +1,7 @@
 /**
  * @file gmp_helper.h
  * 
- * @brief Class with helper functions for gmp operations
+ * @brief Interface of gmp_helper_t.
  * 
  */
 
 
 #include <types.h>
 
+
 typedef struct gmp_helper_t gmp_helper_t;
 
 /**
  * @brief Class with helper functions to manipulate gmp values.
  * 
+ * @ingroup utils
  */
 struct gmp_helper_t {
 
        /**
-        * @brief initialize an mpz_t to a random prime of specified size
+        * Initialize an mpz_t to a random prime of specified size.
         *
         *
         * @param                       this calling object
-        * @param[out] var      mpz_t variable to initialize
+        * @param[out] var      pointer to mpz_t variable to initialize
         * @param[in]           bytes length of given prime in bytes
         * @return              
-        *                              - SUCCCESS
-        *                              - FAILED
-        *                              - OUT_OF_RES
+        *                                      - SUCCCESS
+        *                                      - OUT_OF_RES
         */
        status_t (*init_prime) (gmp_helper_t *this, mpz_t *var, int bytes);
 
        /**
-        * @brief initialize an mpz_t to a random prime of specified size without using gmp 
-        * next prime function! Must be faster then the gmp version
+        * Initialize an mpz_t to a random prime of specified size without using gmp 
+        * next prime function.
         *
         *
         * @param                       this calling object
         * @param[out] var      mpz_t variable to initialize
         * @param[in]           bytes length of given prime in bytes
         * @return              
-        *                              - SUCCCESS
-        *                              - FAILED
-        *                              - OUT_OF_RES
+        *                                      - SUCCCESS
+        *                                      - FAILED if length of prime not as asked. Try again.
+        *                                      - OUT_OF_RES
         */     
        status_t (*init_prime_fast) (gmp_helper_t *this, mpz_t *prime, int bytes);
        
-       /* Convert network form (binary bytes, big-endian) to mpz_t of gmp library.
+       /**
+        *  Convert network form (binary bytes, big-endian) to mpz_t of gmp library.
         * 
-        * mpz_t gets initialized in this function.
+        * The given mpz_t gets initialized in this function.
         * 
-        * @param this                          calling private_gmp_helper_t object
-        * @param mpz_value                     pointer to a mpz_t value
-        * @param data                          chunk_t containing the network form of data
+        * @param this          calling private_gmp_helper_t object
+        * @param mpz_value     pointer to a mpz_t value
+        * @param data          chunk_t containing the network form of data
         */
        void (*chunk_to_mpz) (gmp_helper_t *this,mpz_t *mpz_value, chunk_t data);
        
-       /* Convert mpz_t to network form (binary bytes, big-endian).
+       /**
+        * Convert mpz_t to network form (binary bytes, big-endian).
         * 
-        * @param this                          calling private_gmp_helper_t object
-        * @param mpz_value                     mpz_value to convert
-        * @param data                          chunk_t where the data are written to
-        * @param bytes                         number of bytes to copy 
+        * @param this          calling private_gmp_helper_t object
+        * @param mpz_value     mpz_value to convert
+        * @param data          chunk_t where the data are written to
+        * @param bytes         number of bytes to copy 
         * 
-        * @return                                      
-        *                                                      - SUCCESS
-        *                                                      - OUT_OF_RES
-        *                                                      - FAILED if mpz_t value was longer then given bytes count
+        * @return                      
+        *                                      - SUCCESS
+        *                                      - OUT_OF_RES
+        *                                      - FAILED if mpz_t value was longer then given bytes count
         */
        status_t (*mpz_to_chunk) (gmp_helper_t *this,mpz_t *mpz_value, chunk_t *data,size_t bytes);
 
@@ -95,8 +98,7 @@ struct gmp_helper_t {
         * @brief Destroys an gmp_helper_t object.
         *
         * @param this  gmp_helper_t object to destroy
-        * @return              
-        *                              SUCCESS in any case
+        * @return              SUCCESS in any case
         */
        status_t (*destroy) (gmp_helper_t *this);
 };
@@ -105,10 +107,11 @@ struct gmp_helper_t {
  * Creates a new gmp_helper_t object
  * 
  * @return
- *                                                     - gmp_helper_t if successfully
+ *                                                     - gmp_helper_t object
  *                                                     - NULL if out of ressources
+ * 
+ * @ingroup utils
  */
 gmp_helper_t *gmp_helper_create();
 
-
 #endif /*GMP_HELPER_H_*/