diff --git a/doc/Doxyfile b/doc/Doxyfile index 38341f0..a8e49dc 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -159,7 +159,7 @@ JAVADOC_AUTOBRIEF = NO # will behave just like regular Qt-style comments (thus requiring # an explicit \brief command for a brief description.) -QT_AUTOBRIEF = NO +QT_AUTOBRIEF = YES # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen # treat a multi-line C++ special comment block (i.e. a block of //! or /// @@ -207,7 +207,7 @@ TCL_SUBST = # For instance, some of the names that are used will be different. The list # of all members will be omitted, etc. -OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_FOR_C = YES # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java # sources only. Doxygen will then generate output that is more tailored for @@ -447,7 +447,7 @@ HIDE_SCOPE_NAMES = NO # will put a list of the files that are included by a file in the documentation # of that file. -SHOW_INCLUDE_FILES = YES +SHOW_INCLUDE_FILES = NO # If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen # will list include files with double quotes in the documentation @@ -701,7 +701,7 @@ EXCLUDE_SYMLINKS = NO # against the file with absolute path, so to exclude all test directories # for example use the pattern */test/* -EXCLUDE_PATTERNS = +EXCLUDE_PATTERNS = */internal/* # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the @@ -754,7 +754,7 @@ INPUT_FILTER = # info on how filters are used. If FILTER_PATTERNS is empty or if # non of the patterns match the file name, INPUT_FILTER is applied. -FILTER_PATTERNS = +FILTER_PATTERNS = # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using # INPUT_FILTER) will be used to filter the input files when producing source @@ -1468,13 +1468,13 @@ ENABLE_PREPROCESSING = YES # compilation will be performed. Macro expansion can be done in a controlled # way by setting EXPAND_ONLY_PREDEF to YES. -MACRO_EXPANSION = NO +MACRO_EXPANSION = YES # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES # then the macro expansion is limited to the macros specified with the # PREDEFINED and EXPAND_AS_DEFINED tags. -EXPAND_ONLY_PREDEF = NO +EXPAND_ONLY_PREDEF = YES # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files # pointed to by INCLUDE_PATH will be searched when a #include is found. @@ -1502,7 +1502,10 @@ INCLUDE_FILE_PATTERNS = # undefined via #undef or recursively expanded use the := operator # instead of the = operator. -PREDEFINED = +PREDEFINED = FOUG_LIB_EXPORT= \ + FOUG_LIBSUPPORT_EXPORT= \ + FOUG_DATAX_LIBSTL_EXPORT= \ + FOUG_HAVE_STDINT_H=1 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. diff --git a/src/endian.c b/src/endian.c index bfc12cd..1762a67 100644 --- a/src/endian.c +++ b/src/endian.c @@ -10,7 +10,6 @@ typedef union uint8_t bytes[4]; } _internal_foug_int_bytes_32_convert_t; -/*! Endianness (byte order) of the host's CPU architecture */ foug_endianness_t foug_host_endianness() { _internal_foug_int_bytes_32_convert_t conv; diff --git a/src/endian.h b/src/endian.h index d3d33b2..20c5c8b 100644 --- a/src/endian.h +++ b/src/endian.h @@ -3,6 +3,7 @@ #include "global.h" +/*! This enum identifies endian representations of numbers */ typedef enum { FOUG_LITTLE_ENDIAN, @@ -11,6 +12,7 @@ typedef enum FOUG_OTHER_ENDIAN } foug_endianness_t; +/*! Returns endianness (byte order) of the host's CPU architecture */ FOUG_LIB_EXPORT foug_endianness_t foug_host_endianness(); #endif /* FOUG_ENDIAN_H */ diff --git a/src/error.h b/src/error.h index a2a98e0..28314ff 100644 --- a/src/error.h +++ b/src/error.h @@ -3,18 +3,33 @@ #include "global.h" -/* Common errors */ +/*! This enum defines common errors */ typedef enum { + /*! No error occurred, success */ FOUG_DATAX_NO_ERROR = 0, + + /*! Pointer on argument foug_transfer_t is NULL */ FOUG_DATAX_NULL_TRANSFER_ERROR = -1, + + /*! Pointer on argument buffer is NULL */ FOUG_DATAX_NULL_BUFFER_ERROR = -2, + + /*! Argument buffer's size is too small */ FOUG_DATAX_INVALID_BUFFER_SIZE_ERROR = -3, + + /*! An error occurred with the argument foug_stream_t (check foug_stream_error()) */ FOUG_DATAX_STREAM_ERROR = -4, + + /*! Operation was stopped by user (foug_task_control_t::handle_progress_func() returned false) */ FOUG_DATAX_TASK_STOPPED_ERROR = -5 + } foug_datax_error_t; +/*! Returns true if \p code == FOUG_DATAX_NO_ERROR */ FOUG_LIB_EXPORT foug_bool_t foug_datax_no_error(int code); + +/*! Returns true if \p code != FOUG_DATAX_NO_ERROR */ FOUG_LIB_EXPORT foug_bool_t foug_datax_error(int code); #endif /* FOUG_DATAX_C_ERROR_H */ diff --git a/src/global.h b/src/global.h index e74b5e1..88b4092 100644 --- a/src/global.h +++ b/src/global.h @@ -47,15 +47,20 @@ typedef unsigned long long uint64_t; #endif /* FOUG_USE_STDINT_H */ +/*! Typedef for boolean type */ typedef int foug_bool_t; -typedef float foug_real32_t; -typedef double foug_real64_t; +/*! This enum defines true/false boolean values */ enum foug_bool_value { FOUG_FALSE = 0, FOUG_TRUE = 1 }; +/*! Typedef for 32bit real type (float) */ +typedef float foug_real32_t; +/*! Typedef for 64bit real type (double) */ +typedef double foug_real64_t; + #ifndef FOUG_INLINE # if defined(__GNUC__) # define FOUG_INLINE __inline__ /* Compatible with C90 */ diff --git a/src/stream.c b/src/stream.c index 619f84d..6dfa462 100644 --- a/src/stream.c +++ b/src/stream.c @@ -4,9 +4,6 @@ #include #include -/*! - * \brief Installs a null stream - */ void foug_stream_set_null(foug_stream_t* stream) { memset(stream, 0, sizeof(foug_stream_t)); @@ -38,9 +35,6 @@ static size_t foug_stream_stdio_write(void* cookie, return fwrite(ptr, item_size, item_count, (FILE*) cookie); } -/*! - * \brief Configures \p stream for standard FILE* - */ void foug_stream_set_stdio(foug_stream_t* stream, FILE* file) { stream->cookie = file; @@ -50,9 +44,6 @@ void foug_stream_set_stdio(foug_stream_t* stream, FILE* file) stream->write_func = foug_stream_stdio_write; } -/*! - * \brief Returns true if the current read and write position is at the end of the stream - */ foug_bool_t foug_stream_at_end(foug_stream_t* stream) { if (stream != NULL && stream->at_end_func != NULL) @@ -60,14 +51,6 @@ foug_bool_t foug_stream_at_end(foug_stream_t* stream) return 0; } -/*! - * \brief Checks error indicator - * - * Checks if the error indicator associated with \p stream is set, returning a value different from - * zero if it is. - * - * This indicator is generally set by a previous operation on the \p stream that failed. - */ int foug_stream_error(foug_stream_t* stream) { if (stream != NULL && stream->error_func != NULL) @@ -75,39 +58,16 @@ int foug_stream_error(foug_stream_t* stream) return 0; } -/*! - * \brief Reads block of data from stream - * - * Reads an array of \p item_count elements, each one with a \p item_size of size bytes, from the - * \p stream and stores them in the block of memory specified by \p ptr. - * - * The total amount of bytes read if successful is (item_size * item_count). - * - * \return The total number of elements successfully read is returned. - * If this number differs from the \p item_count argument, either a reading error occurred - * or the end-of-file was reached while reading. In both cases, the proper indicator is set, - * which can be checked with foug_stream_error() and foug_stream_at_end(), respectively. - * If either \p item_size or \p item_count is zero, the function returns zero and both the - * stream state and the content pointed by \p ptr remain unchanged. - */ -size_t foug_stream_read(foug_stream_t* stream, void *ptr, size_t item_size, size_t item_count) +size_t foug_stream_read(foug_stream_t* stream, void *ptr, size_t size, size_t count) { if (stream != NULL && stream->read_func != NULL) - return stream->read_func(stream->cookie, ptr, item_size, item_count); + return stream->read_func(stream->cookie, ptr, size, count); return 0; } -/*! - * \brief Writes block of data to stream - * - * Writes an array of \p item_count elements, each one with a \p item_size of size bytes, from the - * block of memory pointed by \p ptr to the current position in the \p stream. - * - * The total amount of bytes written is (item_size * item_count). - */ -size_t foug_stream_write(foug_stream_t* stream, const void *ptr, size_t item_size, size_t item_count) +size_t foug_stream_write(foug_stream_t* stream, const void *ptr, size_t size, size_t count) { if (stream != NULL && stream->write_func != NULL) - return stream->write_func(stream->cookie, ptr, item_size, item_count); + return stream->write_func(stream->cookie, ptr, size, count); return 0; } diff --git a/src/stream.h b/src/stream.h index 90c86a9..7498f2f 100644 --- a/src/stream.h +++ b/src/stream.h @@ -2,11 +2,10 @@ #define FOUG_C_STREAM_H #include "global.h" -#include "memory.h" #include -/*! \brief Stream that can get input from an arbitrary data source or can write output to an - * arbitrary data sink +/*! Stream that can get input from an arbitrary data source or can write output to an arbitrary + * data sink. * * This is pretty much the same as * @@ -16,35 +15,93 @@ * implemented by defining hook functions that know how to read/write the data. * */ -typedef struct +struct foug_stream { + /*! Opaque pointer on the user stream, passed as first argument to hook functions */ void* cookie; - foug_bool_t (*at_end_func)(void*); - int (*error_func)(void*); - size_t (*read_func)(void*, void*, size_t, size_t); - size_t (*write_func)(void*, const void*, size_t, size_t); -} foug_stream_t; + /*! Pointer on a function that checks end-of-stream indicator. + * + * Checks whether the end-of-stream indicator associated with stream pointed by \p cookie + * is set, returning FOUG_TRUE if is. + * + * The function should behaves like C standard feof() + */ + foug_bool_t (*at_end_func)(void* cookie); + + /*! Pointer on a function that checks error indicator. + * + * Checks if the error indicator associated with stream pointed by \p cookie is set, returning + * a value different from zero if it is. + * + * The function should behaves like C standard ferror() + */ + int (*error_func)(void* cookie); + + /*! Pointer on a function that reads block of data from stream. + * + * \details Reads an array of \p count elements, each one with a size of \p size bytes, from the + * stream pointed by \p cookie and stores them in the block of memory specified by \p ptr + * + * The function should behaves like C standard fread() + * + * \returns The total number of elements successfully read + */ + size_t (*read_func)(void* cookie, void* ptr, size_t size, size_t count); + + /*! Pointer on a function that writes block of data to stream. + * + * \details Writes an array of \p count elements, each one with a size of \p size bytes, from the + * block of memory pointed by \p ptr to the current position in the stream pointed by \p cookie + * + * The function should behaves like C standard fwrite() + * + * \returns The total number of elements successfully written + */ + size_t (*write_func)(void* cookie, const void* ptr, size_t size, size_t count); +}; + +/*! Convenient typedef for struct foug_stream */ +typedef struct foug_stream foug_stream_t; /* Initialization */ +/*! Installs a null stream */ FOUG_LIB_EXPORT void foug_stream_set_null(foug_stream_t* stream); + +/*! Configures \p stream for standard FILE* (cookie will hold \p file) */ FOUG_LIB_EXPORT void foug_stream_set_stdio(foug_stream_t* stream, FILE* file); /* Services */ +/*! Safe and convenient function for foug_stream::at_end_func(). + * + * Basically the same as : \code stream->at_end_func(stream->cookie) \endcode + */ FOUG_LIB_EXPORT foug_bool_t foug_stream_at_end(foug_stream_t* stream); +/*! Safe and convenient function for foug_stream::error_func(). + * + * Basically the same as : \code stream->error_func(stream->cookie) \endcode + */ FOUG_LIB_EXPORT int foug_stream_error(foug_stream_t* stream); +/*! Safe and convenient function for foug_stream::read_func(). + * + * Basically the same as : \code stream->read_func(stream->cookie) \endcode + */ FOUG_LIB_EXPORT size_t foug_stream_read(foug_stream_t* stream, void* ptr, - size_t item_size, - size_t item_count); + size_t size, + size_t count); +/*! Safe and convenient function for foug_stream::write_func(). + * + * Basically the same as : \code stream->write_func(stream->cookie) \endcode + */ FOUG_LIB_EXPORT size_t foug_stream_write(foug_stream_t* stream, const void* ptr, - size_t item_size, - size_t item_count); + size_t size, + size_t count); #endif /* FOUG_C_STREAM_H */ diff --git a/src/task_control.c b/src/task_control.c index 7ee5b29..2a093ae 100644 --- a/src/task_control.c +++ b/src/task_control.c @@ -3,13 +3,6 @@ #include #include -/*! - * \brief Calls a function that does something with progress value \p progress_pc (eg. update - * a progress bar in the UI) - * - * The return value is important : it is used as an interruption request status. If \c true then the - * corresponding task can continue, otherwise it should abort as soon as possible. - */ foug_bool_t foug_task_control_handle_progress(foug_task_control_t* ctrl, uint8_t progress_pc) { if (ctrl != NULL && ctrl->handle_progress_func != NULL) @@ -17,12 +10,6 @@ foug_bool_t foug_task_control_handle_progress(foug_task_control_t* ctrl, uint8_t return 1; } -/*! - * \brief Converts \p value as a percentage - * - * \p value is assumed to be relative to the interval (range) defined by - * [ \p range_min , \p range_max ] - */ uint8_t foug_percentage(size_t range_min, size_t range_max, size_t value) { if (value >= range_max) diff --git a/src/task_control.h b/src/task_control.h index b8872e1..504d119 100644 --- a/src/task_control.h +++ b/src/task_control.h @@ -4,16 +4,39 @@ #include "global.h" #include "memory.h" -typedef struct foug_task_control +/*! Provides control over a general task. + * + * "Control" here means task progress handling and interruption request (abort). + */ +struct foug_task_control { + /*! Opaque pointer on a user task object, passed as first argument to hook functions */ void* cookie; - foug_bool_t (*handle_progress_func)(void*, uint8_t); -} foug_task_control_t; -FOUG_LIB_EXPORT -foug_bool_t foug_task_control_handle_progress(foug_task_control_t* ctrl, uint8_t progress_pc); + /*! Pointer on a function that that does something with progress value \p progress (eg update + * a UI progress bar) + * + * The return value is important : it is used as an interruption request status. If FOUG_TRUE then + * the current task can continue, otherwise it should abort as soon as possible. + */ + foug_bool_t (*handle_progress_func)(void* cookie, uint8_t progress); +}; -FOUG_LIB_EXPORT -uint8_t foug_percentage(size_t range_min, size_t range_max, size_t value); +/*! Convenient typedef for struct foug_task_control */ +typedef struct foug_task_control foug_task_control_t; + +/*! Safe and convenient function for foug_task_control::handle_progress_func() + * + * Basically the same as : \code ctrl->handle_progress_func(ctrl->cookie, progress_pc) \endcode + */ +FOUG_LIB_EXPORT foug_bool_t foug_task_control_handle_progress(foug_task_control_t* ctrl, + uint8_t progress_pc); + +/*! Utility function that converts \p value as a percentage + * + * \p value is assumed to be relative to the interval (range) defined by + * [ \p range_min , \p range_max ] + */ +FOUG_LIB_EXPORT uint8_t foug_percentage(size_t range_min, size_t range_max, size_t value); #endif /* FOUG_C_TASK_CONTROL_H */