diff --git a/src/interfaces/reader/eas3.c b/src/interfaces/reader/eas3.c index 8bc999e..f3e2985 100644 --- a/src/interfaces/reader/eas3.c +++ b/src/interfaces/reader/eas3.c @@ -102,15 +102,11 @@ || | | \ | \/ | | | |___ | |__| | \| |___ | | |__| | \| ___] || || || \************************************************************************************************************/ - -/*----------------------------------------------------------------------------------------------------------*\ -! ! -! DESCRIPTION: ! -! ------------ ! -! This macro is used to write an additional chunck of size length to the auxilliary ! -! information. ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Enqueues a chunck of size length to the auxilliary information. + */ +/*================================================================================================*/ #define aux_enqueue(aux, chunck, chunck_len) \ { \ if (aux.pos + chunck_len > aux.len) \ @@ -125,6 +121,11 @@ aux.pos += chunck_len; \ } +/*================================================================================================*/ +/** + * @details Dequeues a chunck of size length from the auxilliary information. + */ +/*================================================================================================*/ #define aux_dequeue(aux, chunck, chunck_len) \ { \ if(aux.pos + chunck_len <= aux.len) { \ @@ -135,37 +136,14 @@ } \ } -/*----------------------------------------------------------------------------------------------------------*\ -! ! -! DESCRIPTION: ! -! ------------ ! -! This function converts the endianess of half, single or double precision values. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! value void* - Memory address of the parame- ! -! ter to be converted. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! - - ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description ! -! ---- ------ --------- ------- ----------- ! -! 30.04.2019 Patrick Vogler B87D120 V 0.1.0 function created ! -! 21.11.2019 Patrick Vogler B87E7E4 V 0.1.0 functionality expanded ! -! to 32 bit integers ! -! 21.11.2019 Patrick Vogler B87E7E4 V 0.1.0 functionality expanded ! -! to 16 bit integers ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Converts the endianess of half, single, or double precision values. + * + * @param[inout] value Pointer to the parameter to be converted. + * @param[in] accuracy Precision/accuracy of the pointed parameter. + */ +/*================================================================================================*/ static void endian_conversion(void *value, uint8_t const accuracy) @@ -219,15 +197,13 @@ endian_conversion(void *value, } } -/*----------------------------------------------------------------------------------------------------------*\ -! ! -! DESCRIPTION: ! -! ------------ ! -! This function deallocates the data structure used to store a numerical dataset ! -! and can be called if an error occurs or once the data is no longer needed. ! -! The deallocation will be carried out down to the structure levels that have been allocated. ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Deallocates the provided eas3_data structure including all contained data. + * + * @param[in] data Pointer to eas3_data structure to be filled. + */ +/*================================================================================================*/ void eas3_free_data(eas3_data* data) { @@ -263,6 +239,14 @@ eas3_free_data(eas3_data* data) } } +/*================================================================================================*/ +/** + * @details Adds a parameter name to the linked list inside the eas3_data structure. + * + * @param[in] data Pointer to eas3_data structure to be filled. + * @param[in] name Name to be added to the linked list. + */ +/*================================================================================================*/ void eas3_add_param_name(eas3_data *const data, char *name) { @@ -429,40 +413,17 @@ bwc_to_eas3(bwc_stream *const stream, eas3_data *const data) return 0; } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: uchar read_eas3_header(bwc_data *const data) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function opens an eas3 file and checks it for its validity. Once the specified file ! -! has been verified, its header and flow field data is read and stored in the bwc_data ! -! structure. ! -! ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! filename char* - Defines the filename of the eas3 file ! -! that is to be opened and read. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! file - Defines a structure used to store all ! -! the relevant parameters and the data ! -! field of an eas3 file. ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 20.06.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Reads the header from an open eas3 file pointer parsing the header information into + * the eas3_data structure argument. + * + * @param[in] fp Readily opened file pointer. + * @param[inout] data Structure to store eas3 data. + * + * @retval uchar + */ +/*================================================================================================*/ static uchar read_eas3_header(FILE *const fp, eas3_data *const data) { @@ -772,40 +733,17 @@ read_eas3_header(FILE *const fp, eas3_data *const data) return 0; } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: uchar read_eas3_header(bwc_data *const data) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function opens an eas3 file and checks it for its validity. Once the specified file ! -! has been verified, its header and flow field data is read and stored in the bwc_data ! -! structure. ! -! ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! filename char* - Defines the filename of the eas3 file ! -! that is to be opened and read. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! file - Defines a structure used to store all ! -! the relevant parameters and the data ! -! field of an eas3 file. ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 20.06.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Writes the header information from the eas3_data structure into the open eas3 + * file pointer. + * + * @param[in] fp Readily opened file pointer. + * @param[inout] data Structure to store eas3 data. + * + * @retval uchar + */ +/*================================================================================================*/ static uchar write_eas3_header(FILE *const fp, eas3_data *const data) { @@ -1019,40 +957,16 @@ write_eas3_header(FILE *const fp, eas3_data *const data) || | |__| |__] |___ | |___ | |__| | \| |___ | | |__| | \| ___] || || || \************************************************************************************************************/ -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: bwc_data* read_eas3(const char* const filename) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function opens an eas3 file and checks it for its validity. Once the specified file ! -! has been verified, its header and flow field data is read and stored in the bwc_data ! -! structure. ! -! ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! filename char* - Defines the filename of the eas3 file ! -! that is to be opened and read. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! file - Defines a structure used to store all ! -! the relevant parameters and the data ! -! field of an eas3 file. ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 20.06.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Opens an eas3 file and checks it for its validity. Then, it reads header and flow + * field data and returns a filled instance of the eas3_data structure. + * + * @param[in] filename Name of the eas3 file. + * + * @retval eas3_data* + */ +/*================================================================================================*/ eas3_data* read_eas3(char *const filename) { @@ -1215,40 +1129,16 @@ read_eas3(char *const filename) return data; } -/*----------------------------------------------------------------------------------------------------------*\ -! FUNCTION NAME: uchar write_eas3(bwc_data *const file, char *const filename) ! -! -------------- ! -! ! -! DESCRIPTION: ! -! ------------ ! -! This function creates a valid eas3 file from the information stored in the bwc_data ! -! structure. ! -! ! -! PARAMETERS: ! -! ----------- ! -! Variable Type Description ! -! -------- ---- ----------- ! -! filename char* - Defines the filename of the eas3 file ! -! that is to be opened and read. ! -! ! -! file bwc_data* - Defines a structure used to store all ! -! the relevant parameters and the data ! -! field of an eas3 file. ! -! ! -! RETURN VALUE: ! -! ------------- ! -! Type Description ! -! ---- ----------- ! -! uchar - Returns an unsigned char for error handling. ! -! ! -! DEVELOPMENT HISTORY: ! -! -------------------- ! -! ! -! Date Author Change Id Release Description Of Change ! -! ---- ------ --------- ------- --------------------- ! -! 20.06.2018 Patrick Vogler B87D120 V 0.1.0 function created ! -! ! -\*----------------------------------------------------------------------------------------------------------*/ +/*================================================================================================*/ +/** + * @details Opens an eas3 file and writes the content from the provided eas3_data structure. + * + * @param[in] data Data to be written into the eas3 file. + * @param[in] filename Name of the eas3 file. + * + * @retval uchar + */ +/*================================================================================================*/ uchar write_eas3(eas3_data *const data, char *const filename) {