cleaned up and fixed ASN.1 documentation.

3 files changed, 43 insertions, 83 deletions

diff --git a/lib/x509_ASN.y b/lib/x509_ASN.y
index abe38013aa..9a79296e12 100755
--- a/lib/x509_ASN.y
+++ b/lib/x509_ASN.y
@@ -456,18 +456,15 @@ yylex()
 
 /**
   * asn1_parser_asn1 - function used to start the parse algorithm.
-  * @file_name: file name to parse
-  * @pointer: return the pointer to the structure
+  * @file_name: specify the path and the name of file that contains ASN.1 declarations.
+  * @pointer: return the pointer to the structure created from 
+  *   "file_name" ASN.1 declarations.  
+  * Description:
   *
   * Creates the structures needed to manage the definitions included in *FILE_NAME file.
   *
-  * Input Parameter: 
-  *   char *file_name: specify the path and the name of file that contains ASN.1 declarations.
-  * Output Parameter:
-  *   node_asn **pointer : return the pointer to the structure created from 
-  *   "file_name" ASN.1 declarations.  
+  * Returns:
   *
-  * Return Value:
   * ASN_OK: the file has a correct syntax and every identifier is known. 
   * ASN_FILE_NOT_FOUND: an error occured while opening FILE_NAME.
   * ASN_SYNTAX_ERROR: the syntax is not correct.
@@ -511,16 +508,15 @@ int asn1_parser_asn1(char *file_name,node_asn **pointer){
 
 /**
   * asn1_parser_asn1_file_c - function that generates a C structure from an ASN1 file
-  * @file_name : file name to parse
+  * @file_name: specify the path and the name of file that contains ASN.1 declarations.
+  * Description:
   *
   * Creates a file containing a C vector to use to manage the definitions included in
   * *FILE_NAME file. If *FILE_NAME is "/aa/bb/xx.yy" the file created is "/aa/bb/xx_asn1_tab.c",
   * and the vector is "xx_asn1_tab".
   *
-  * Input Parameter: 
-  *  char *file_name: specify the path and the name of file that contains ASN.1 declarations.
+  * Returns:
   *
-  * Return Value:
   *  ASN_OK: the file has a correct syntax and every identifier is known. 
   *  ASN_FILE_NOT_FOUND: an error occured while opening FILE_NAME.
   *  ASN_SYNTAX_ERROR: the syntax is not correct.
diff --git a/lib/x509_asn1.c b/lib/x509_asn1.c
index 4e01b543ba..337f8de073 100755
--- a/lib/x509_asn1.c
+++ b/lib/x509_asn1.c
@@ -444,16 +444,13 @@ _asn1_convert_integer(char *value,unsigned char *value_out,int value_out_size, i
   * asn1_create_tree - Creates the structures needed to manage the ASN1 definitions.
   * @root: specify vector that contains ASN.1 declarations
   * @pointer: return the pointer to the structure created by *ROOT ASN.1 declarations
+  * Description:
   *
   * Creates the structures needed to manage the ASN1 definitions. ROOT is a vector created by
   * 'asn1_parser_asn1_file_c' function.
   *
-  * Input Parameter: 
-  *  static_asn *root: specify vector that contains ASN.1 declarations.
-  * Output Parameter:
-  *  node_asn **pointer : return the pointer to the structure created by *ROOT ASN.1 declarations.  
+  * Returns:
   *
-  * Return Value:
   *  ASN_OK: structure created correctly. 
   *  ASN_GENERIC_ERROR: an error occured while structure creation  
   **/
@@ -789,13 +786,12 @@ asn1_visit_tree(node_asn *pointer,char *name)
 /**
   * asn1_delete_structure - Deletes the structure *POINTER. 
   * @root: pointer to the structure that you want to delete.
+  * Description:
   * 
   * Deletes the structure *POINTER. 
   * 
-  * Input Parameters:
-  *   node_asn *pointer: pointer to the structure that you want to delete.
-  * 
-  * Return Value:
+  * Returns:
+  *
   *   ASN_OK: everything OK
   *   ASN_ELEMENT_NOT_FOUND: pointer==NULL.
   *
@@ -922,18 +918,12 @@ _asn1_copy_structure2(node_asn *root,char *source_name)
   * @source_name: the name of the type of the new structure (must be inside p_structure).
   * @pointer: pointer to the structure created. 
   * @dest_name: the name of the new structure.
+  * Description:
   *
   * Creates a structure called DEST_NAME of type SOURCE_NAME.
   *
-  * Input Parameters:
-  *  node_asn *p_structure: pointer to the structure returned by "parser_asn1" function 
-  *  char *source_name: the name of the type of the new structure (must be inside p_structure).
-  *  char *dest_name: the name of the new structure.
-  *
-  * Output Parameter:
-  *  node_asn **pointer : pointer to the structure created. 
+  * Returns:
   *
-  * Return Value:
   *  ASN_OK: creation OK
   *  ASN_ELEMENT_NOT_FOUND: SOURCE_NAME isn't known
   * 
@@ -1006,26 +996,23 @@ _asn1_append_sequence_set(node_asn *node)
   * asn1_write_value - Set the value of one element inside a structure.
   * @node_root: pointer to a structure
   * @name: the name of the element inside the structure that you want to set.
-  * @value: vector used to specify the value to set. 
-  * @len: number of bytes of *value to use
+  * @value: vector used to specify the value to set. If len is >0, 
+  * VALUE must be a two's complement form integer.
+  * if len=0 *VALUE must be a null terminated string with an integer value. 
+  * @len: number of bytes of *value to use to set the value: value[0]..value[len-1]
+  *  or 0 if value is a null terminated string
+  * Description:
   *
   * Set the value of one element inside a structure.
   * 
-  * Input Parameters:
-  *   node_asn *pointer: pointer to a structure
-  *   char *name: the name of the element inside the structure that you want to set.
-  *   unsigned char *value: vector used to specify the value to set. If len is >0, 
-  *                         *VALUE must be a two's complement form integer.
-  *                         if len=0 *VALUE must be a null terminated string with an integer value.
-  *   int len: number of bytes of *value to use to set the value: value[0]..value[len-1]
-  *            or 0 if value is a null terminated string
+  * Returns:
   * 
-  * Return Value:
   *   ASN_OK: set value OK
   *   ASN_ELEMENT_NOT_FOUND: NAME is not a valid element.
   *   ASN_VALUE_NOT_VALID: VALUE has a wrong format.
   * 
-  * Examples:  description for each type
+  * Examples:  
+  *   description for each type
   *   INTEGER: VALUE must contain a two's complement form integer.
   *            value[0]=0xFF ,               len=1 -> integer=-1
   *            value[0]=0xFF value[1]=0xFF , len=2 -> integer=-1
@@ -1312,25 +1299,20 @@ asn1_write_value(node_asn *node_root,char *name,unsigned char *value,int len)
   * @root: pointer to a structure
   * @name: the name of the element inside a structure that you want to read.
   * @value: vector that will contain the element's content. 
+  * VALUE must be a pointer to memory cells already allocated.
   * @len: number of bytes of *value: value[0]..value[len-1]
+  * Description:
   *
   * Returns the value of one element inside a structure.
   * 
-  * Input Parameters:
-  *   node_asn *pointer: pointer to a structure
-  *   char *name: the name of the element inside a structure that you want to read.
-  * 
-  * Output Parameters:
-  *   unsigned char *value: vector that will contain the element's content. 
-  *                         VALUE must be a pointer to memory cells already allocated.
-  *   int *len: number of bytes of *value: value[0]..value[len-1]
-  * 
-  * Return Value:
+  * Returns:
+  *
   *   ASN_OK: set value OK
   *   ASN_ELEMENT_NOT_FOUND: NAME is not a valid element.
   *   ASN_VALUE_NOT_FOUND: there isn't any value for the element selected.
   * 
-  * Examples: a description for each type
+  * Examples: 
+  *   a description for each type
   *   INTEGER: VALUE will contain a two's complement form integer.
   *            integer=-1  -> value[0]=0xFF , len=1
   *            integer=1   -> value[0]=0x01 , len=1
diff --git a/lib/x509_der.c b/lib/x509_der.c
index 78b8b6b04f..7f0d76a467 100644
--- a/lib/x509_der.c
+++ b/lib/x509_der.c
@@ -808,22 +808,15 @@ _asn1_ordering_set_of(unsigned char *der,node_asn *node)
 /**
   * asn1_create_der - Creates the DER encoding for the NAME structure
   * @root: pointer to a structure
-  * @name: the name of the structure you want to encode
-  * @der: vector that will contain the DER encoding. 
+  * @name: the name of the structure you want to encode (it must be inside *POINTER).
+  * @der: vector that will contain the DER encoding. DER must be a pointer to memory cells already allocated.
   * @len: number of bytes of *der: der[0]..der[len-1]
+  * Description:
   *
   * Creates the DER encoding for the NAME structure (inside *POINTER structure).
   * 
-  * Input Parameters:
-  *   node_asn *pointer: pointer to a structure
-  *   char *name: the name of the structure you want to encode (it must be inside *POINTER).
-  * 
-  * Output Parameters:
-  *   unsigned char *der: vector that will contain the DER encoding. 
-  *                       DER must be a pointer to memory cells already allocated.
-  *   int *len: number of bytes of *der: der[0]..der[len-1]
-  * 
-  * Return Value:
+  * Returns:
+  *
   *   ASN_OK: DER encoding OK
   *   ASN_ELEMENT_NOT_FOUND: NAME is not a valid element.
   *   ASN_VALUE_NOT_FOUND: there is an element without a value.
@@ -970,19 +963,16 @@ asn1_create_der(node_asn *root,char *name,unsigned char *der,int *len)
   * @root: pointer to a structure
   * @der: vector that contains the DER encoding. 
   * @len: number of bytes of *der: der[0]..der[len-1]
+  * Description:
   *
   * Fill the structure *POINTER with values of a DER encoding string. The sructure must just be
   * created with function 'create_stucture'.
   * 
-  * Input Parameters:
-  *   node_asn *pointer: pointer to the structure that you want to fill.
-  *   unsigned char *der: vector that contains the DER encoding. 
-  *   int len: number of bytes of *der: der[0]..der[len-1]
-  * 
-  * Return Value:
+  * Returns:
+  *
   *   ASN_OK: DER encoding OK
   *   ASN_ELEMENT_NOT_FOUND: NAME is not a valid element.
-  *   ASN_TAG_ERROR, ASN_DER_ERROR: the der encoding doesn't match the structure NAME.  
+  *   ASN_TAG_ERROR,ASN_DER_ERROR: the der encoding doesn't match the structure NAME.  
   **/
 
 int 
@@ -1209,6 +1199,7 @@ asn1_get_der(node_asn *root,unsigned char *der,int len)
   * @name_element: an element of NAME structure.
   * @start: the position of the first byte of NAME_ELEMENT decoding (der[*start]) 
   * @end: the position of the last byte of NAME_ELEMENT decoding (der[*end])
+  * Description:
   * 
   * Find the start and end point of an element in a DER encoding string. I mean that if you
   * have a der encoding and you have already used the function "get_der" to fill a structure, it may
@@ -1216,20 +1207,11 @@ asn1_get_der(node_asn *root,unsigned char *der,int len)
   * 
   * Example: the sequence "tbsCertificate" inside an X509 certificate.
   *
-  * Input Parameters:
-  *   node_asn *pointer: the pointer to the structure that is already setted with DER string.
-  *   unsigned char *der: vector that contains the DER encoding. 
-  *   int len: number of bytes of *der: der[0]..der[len-1]
-  *   char *name_element: an element of NAME structure.
-  * 
-  * Output Parameters:
-  *   int *start: the position of the first byte of NAME_ELEMENT decoding (der[*start]) 
-  *   int *end: the position of the last byte of NAME_ELEMENT decoding (der[*end])
-  * 
-  * Return Value:
+  * Returns:
+  *
   *   ASN_OK: DER encoding OK
   *   ASN_ELEMENT_NOT_FOUND: NAME or NAME_ELEMENT is not a valid element.
-  *   ASN_TAG_ERROR, ASN_DER_ERROR: the der encoding doesn't match the structure NAME.
+  *   ASN_TAG_ERROR,ASN_DER_ERROR: the der encoding doesn't match the structure NAME.
   *
   **/
 int