caiyu/gmio
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add more documentation for global header files (just below src/ folder)

Browse Source
This commit is contained in:
Hugues Delorme 2014-02-13 11:18:46 +01:00
parent 3ccd118545
commit c4c08b1e5c
9 changed files with 140 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
doc/Doxyfile
View File

@ -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.

1
src/endian.c
View File

@ -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;

2
src/endian.h
View File

@ -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 */

17
src/error.h
View File

@ -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 */

9
src/global.h
View File

@ -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 */

48
src/stream.c
View File

@ -4,9 +4,6 @@
#include <stdio.h>
#include <stdlib.h>
/*!
* \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;
}

83
src/stream.h
View File

@ -2,11 +2,10 @@
#define FOUG_C_STREAM_H
#include "global.h"
#include "memory.h"
#include <stdio.h>
/*! \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
* <a href="http://www.gnu.org/software/libc/manual/html_mono/libc.html#Custom-Streams">
@ -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 */

13
src/task_control.c
View File

@ -3,13 +3,6 @@
#include <math.h>
#include <string.h>
/*!
* \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)

37
src/task_control.h
View File

@ -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 */