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

Improve generated documentation

Browse Source
This commit is contained in:
Hugues Delorme 2014-11-21 11:39:23 +01:00
parent 666f90857a
commit d2380c7b37
11 changed files with 125 additions and 137 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/Doxyfile
View File

@ -307,7 +307,7 @@ INLINE_GROUPED_CLASSES = NO
# structs, classes, and unions are shown on a separate page (for HTML and Man
# pages) or section (for LaTeX and RTF).
INLINE_SIMPLE_STRUCTS = NO
INLINE_SIMPLE_STRUCTS = YES
# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum
# is documented as struct, union, or enum with the name of the typedef. So
@ -673,7 +673,7 @@ INPUT_ENCODING = UTF-8
# *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py
# *.f90 *.f *.for *.vhd *.vhdl
FILE_PATTERNS =
FILE_PATTERNS = *.h
# The RECURSIVE tag can be used to turn specify whether or not subdirectories
# should be searched for input files as well. Possible values are YES and NO.
@ -1130,7 +1130,7 @@ GENERATE_TREEVIEW = NO
# documentation. Note that a value of 0 will completely suppress the enum
# values from appearing in the overview section.
ENUM_VALUES_PER_LINE = 4
ENUM_VALUES_PER_LINE = 0
# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be
# used to set the initial width (in pixels) of the frame in which the tree

25
doc/main_page.cpp
View File

@ -14,29 +14,8 @@ GeomIO is a fast and portable C library for reading and writing geometry data.
\section build_sec BUILDING GeomIO library
The GeomIO library can be built with qmake or cmake.
<b>With qmake :</b>
\code
.../gmio$ cd qmake
.../gmio$ qmake PREFIX_DIR=../gcc-linux64
.../gmio$ make all
.../gmio$ make install
\endcode
If you want static libraries (instead of DLLs) just add "CONFIG+=staticlib" to the qmake command :
\code
.../gmio$ qmake PREFIX_DIR=../gcc-linux64 CONFIG+=staticlib
\endcode
Note that on Windows, qmake complains about deprecated support of backslash '\' characters.
So you may have to escape backslashes like C:\\path\\to\\opencascade or simply use Unix separators
instead C:/path/to/opencascade
<b>With CMake :</b>
<TO_BE_DONE>
The GeomIO library can be built with cmake.
Once makefiles are generated, init tests can be run with "make check"
\section reportbug_sec HOW TO REPORT A BUG

71
src/gmio_core/stream.c
View File

@ -4,57 +4,6 @@
#include <stdio.h>
#include <stdlib.h>
/*! \struct gmio_stream
*
* \details This is pretty much the same as [custom streams]
* (http://www.gnu.org/software/libc/manual/html_mono/libc.html#Custom-Streams) in the GNU C Library
*
* It uses a cookie being basically an opaque pointer on a hidden data type.\n The custom stream is
* implemented by defining hook functions that know how to read/write the data.
*/
/*! \var gmio_bool_t (*gmio_stream::at_end_func)(void*)
*
* Checks whether the end-of-stream indicator associated with stream pointed by \p cookie is set,
* returning GMIO_TRUE if is.
*
* The function should behaves like C standard [feof()]
* (http://pubs.opengroup.org/onlinepubs/007904975/functions/feof.html)
*/
/*! \var int (*gmio_stream::error_func)(void*)
*
* 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()]
* (http://pubs.opengroup.org/onlinepubs/007904975/functions/ferror.html)
*/
/*! \var size_t (*gmio_stream::read_func)(void*, void*, size_t, size_t)
*
* 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()]
* (http://pubs.opengroup.org/onlinepubs/007904975/functions/fread.html)
*
* \returns The total number of elements successfully read
*/
/*! \var size_t (*gmio_stream::write_func)(void*, const void*, size_t, size_t);
*
* 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()]
* (http://pubs.opengroup.org/onlinepubs/007904975/functions/fwrite.html)
*
* \returns The total number of elements successfully written
*/
void gmio_stream_set_null(gmio_stream_t* stream)
{
memset(stream, 0, sizeof(gmio_stream_t));
@ -95,11 +44,6 @@ void gmio_stream_set_stdio(gmio_stream_t* stream, FILE* file)
stream->write_func = gmio_stream_stdio_write;
}
/*! \details Basically the same as :
* \code
* stream->at_end_func(stream->cookie)
* \endcode
*/
gmio_bool_t gmio_stream_at_end(gmio_stream_t* stream)
{
if (stream != NULL && stream->at_end_func != NULL)
@ -107,11 +51,6 @@ gmio_bool_t gmio_stream_at_end(gmio_stream_t* stream)
return 0;
}
/*! \details Basically the same as :
* \code
* stream->error_func(stream->cookie)
* \endcode
*/
int gmio_stream_error(gmio_stream_t* stream)
{
if (stream != NULL && stream->error_func != NULL)
@ -119,11 +58,6 @@ int gmio_stream_error(gmio_stream_t* stream)
return 0;
}
/*! \details Basically the same as :
* \code
* stream->read_func(stream->cookie)
* \endcode
*/
size_t gmio_stream_read(gmio_stream_t* stream, void *ptr, size_t size, size_t count)
{
if (stream != NULL && stream->read_func != NULL)
@ -131,11 +65,6 @@ size_t gmio_stream_read(gmio_stream_t* stream, void *ptr, size_t size, size_t co
return 0;
}
/*! \details Basically the same as :
* \code
* stream->write_func(stream->cookie)
* \endcode
*/
size_t gmio_stream_write(gmio_stream_t* stream, const void *ptr, size_t size, size_t count)
{
if (stream != NULL && stream->write_func != NULL)

88
src/gmio_core/stream.h
View File

@ -6,52 +6,108 @@
GMIO_C_LINKAGE_BEGIN
/*! Stream that can get input from an arbitrary data source or can write output to an arbitrary
* data sink. It can be seen as generalization of the standard FILE*
/*! \brief Stream that can get input from an arbitrary data source or can write
* output to an arbitrary data sink.
*
* It can be seen as generalization of the standard \c FILE*, and is pretty
* much the same as [custom streams]
* (http://www.gnu.org/software/libc/manual/html_mono/libc.html#Custom-Streams)
* in the GNU C Library
*
* It uses a cookie being basically an opaque pointer on a hidden data type.\n
* The custom stream is implemented by defining hook functions that know how
* to read/write the data.
*/
struct gmio_stream
{
/*! Opaque pointer on the user stream, passed as first argument to hook functions */
/*! \brief Opaque pointer on the user stream, passed as first argument to
* hook functions */
void* cookie;
/*! Pointer on a function that checks end-of-stream indicator */
/*! \brief 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 GMIO_TRUE if is.
*
* The function should behaves like C standard [feof()]
* (http://pubs.opengroup.org/onlinepubs/007904975/functions/feof.html)
*/
gmio_bool_t (*at_end_func)(void* cookie);
/*! Pointer on a function that checks error indicator */
int (*error_func)(void* cookie);
/*! \brief 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()]
* (http://pubs.opengroup.org/onlinepubs/007904975/functions/ferror.html)
*/
int (*error_func)(void* cookie);
/*! Pointer on a function that reads block of data from stream */
size_t (*read_func)(void* cookie, void* ptr, size_t size, size_t count);
/*! \brief 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()]
* (http://pubs.opengroup.org/onlinepubs/007904975/functions/fread.html)
*
* \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 */
size_t (*write_func)(void* cookie, const void* ptr, size_t size, size_t count);
/*! \brief 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()]
* (http://pubs.opengroup.org/onlinepubs/007904975/functions/fwrite.html)
*
* \returns The total number of elements successfully written
*/
size_t (*write_func)(void* cookie, const void* ptr, size_t size, size_t count);
};
typedef struct gmio_stream gmio_stream_t;
/* Initialization */
/*! Installs a null stream */
/*! \brief Installs a null stream */
GMIO_LIB_EXPORT void gmio_stream_set_null(gmio_stream_t* stream);
/*! Configures \p stream for standard FILE* (cookie will hold \p file) */
/*! \brief Configures \p stream for standard FILE* (cookie will hold \p file) */
GMIO_LIB_EXPORT void gmio_stream_set_stdio(gmio_stream_t* stream, FILE* file);
/* Services */
/*! Safe and convenient function for gmio_stream::at_end_func() */
/*! \brief Safe and convenient function for gmio_stream::at_end_func()
*
* Same as: \code stream->at_end_func(stream->cookie) \endcode
*/
GMIO_LIB_EXPORT gmio_bool_t gmio_stream_at_end(gmio_stream_t* stream);
/*! Safe and convenient function for gmio_stream::error_func() */
/*! \brief Safe and convenient function for gmio_stream::error_func()
*
* Same as: \code stream->error_func(stream->cookie) \endcode
*/
GMIO_LIB_EXPORT int gmio_stream_error(gmio_stream_t* stream);
/*! Safe and convenient function for gmio_stream::read_func() */
/*! \brief Safe and convenient function for gmio_stream::read_func()
*
* Same as: \code stream->read_func(stream->cookie) \endcode
*/
GMIO_LIB_EXPORT size_t gmio_stream_read(gmio_stream_t* stream,
void* ptr,
size_t size,
size_t count);
/*! Safe and convenient function for gmio_stream::write_func() */
/*! \brief Safe and convenient function for gmio_stream::write_func()
*
* Same as: \code stream->write_func(stream->cookie) \endcode
*/
GMIO_LIB_EXPORT size_t gmio_stream_write(gmio_stream_t* stream,
const void* ptr,
size_t size,

2
src/gmio_core/transfer.h
View File

@ -11,7 +11,7 @@ struct gmio_transfer
/*! The stream object to be used for I/O */
gmio_stream_t stream;
/*! The optional control object used to handle progress of the transfer */
/*! The optional object used to control execution of the transfer */
gmio_task_control_t task_control;
/*! Pointer on a memory buffer used by the transfer for stream operations */

10
src/gmio_stl/stl_format.c
View File

@ -11,16 +11,6 @@
#define _INTERNAL_GMIO_FIXED_BUFFER_SIZE 512
/*! \brief Returns the format of the STL data in \p stream
*
* It will try to read 512 bytes from \p stream into a buffer and then analyses this data to guess
* the format.
*
* Parameter \p data_size must provide the total size (in bytes) of the stream data (e.g. file
* size), it is required to guess endianness in case of binary format.
*
* Returns GMIO_STL_UNKNOWN_FORMAT in case of error.
*/
gmio_stl_format_t gmio_stl_get_format(gmio_stream_t *stream, size_t data_size)
{
char fixed_buffer[_INTERNAL_GMIO_FIXED_BUFFER_SIZE];

10
src/gmio_stl/stl_format.h
View File

@ -17,6 +17,16 @@ enum gmio_stl_format
typedef enum gmio_stl_format gmio_stl_format_t;
/*! \brief Returns the format of the STL data in \p stream
*
* It will try to read 512 bytes from \p stream into a buffer and then analyses this data to guess
* the format.
*
* Parameter \p data_size must provide the total size (in bytes) of the stream data (e.g. file
* size), it is required to guess endianness in case of binary format.
*
* Returns GMIO_STL_UNKNOWN_FORMAT in case of error.
*/
GMIO_LIBSTL_EXPORT
gmio_stl_format_t gmio_stl_get_format(gmio_stream_t* stream, size_t data_size);

26
src/gmio_stl/stl_mesh_creator.h
View File

@ -4,29 +4,35 @@
#include "stl_global.h"
#include "stl_triangle.h"
/*! Provides an interface for the creation of the underlying(hidden) user mesh */
/*! \brief Provides an interface for the creation of the underlying(hidden)
* user mesh
*/
struct gmio_stl_mesh_creator
{
/*! Opaque pointer on the user mesh, passed as first argument to hook functions */
/*! \brief Opaque pointer on the user mesh, passed as first argument to hook
* functions
*/
void* cookie;
/* All function pointers are optional (ie can be set to NULL) */
/*! Pointer on a function that handles declaration of a solid of name \p solid_name .
/*! \brief Pointer on a function that handles declaration of a solid of name
* \p solid_name
*
* This optional function is useful only with STL ascii (ie. gmio_stla_read())
* Optional function useful only with STL ascii (ie. gmio_stla_read())
*/
void (*ascii_begin_solid_func)(void* cookie, const char* solid_name);
/*! Pointer on a function that handles declaration of a mesh with \p tri_count number of triangles.
/*! \brief Pointer on a function that handles declaration of a mesh with
* \p tri_count number of triangles
*
* This optional function is useful only with STL binary (ie. gmio_stlb_read()).
* Optional function useful only with STL binary (ie. gmio_stlb_read()).
*
* The argument \p header contains the header data(80 bytes)
*/
void (*binary_begin_solid_func)(void* cookie, uint32_t tri_count, const uint8_t* header);
/*! Pointer on a function that adds a triangle to the user mesh.
/*! \brief Pointer on a function that adds a triangle to the user mesh
*
* The argument \p triangle is the triangle to be added, note that
* gmio_stl_triangle_t::attribute_byte_count is meaningless for STL ascii.
@ -35,10 +41,10 @@ struct gmio_stl_mesh_creator
*/
void (*add_triangle_func)(void* cookie, uint32_t tri_id, const gmio_stl_triangle_t* triangle);
/*! Pointer on a function that finalizes creation of the user mesh.
/*! \brief Pointer on a function that finalizes creation of the user mesh
*
* This optional function is called at the end of the read process, ie. after all triangles have
* been added
* Optional function called at the end of the read process, ie. after all
* triangles have been added
*/
void (*end_solid_func)(void* cookie);
};

10
src/gmio_stl/stl_triangle.h
View File

@ -3,7 +3,9 @@
#include "stl_global.h"
/*! Cartesian coordinate entity in 3D space, specifically tailored for STL needs (single-float) */
/*! \brief Cartesian coordinate entity in 3D space, specifically tailored for
* STL needs (single-float)
*/
struct gmio_stl_coords
{
gmio_real32_t x;
@ -13,14 +15,16 @@ struct gmio_stl_coords
typedef struct gmio_stl_coords gmio_stl_coords_t;
/*! STL mesh triangle defined three geometric vertices and an orientation(normal) */
/*! \brief STL mesh triangle defined three geometric vertices and an
* orientation(normal)
*/
struct gmio_stl_triangle
{
gmio_stl_coords_t normal;
gmio_stl_coords_t v1;
gmio_stl_coords_t v2;
gmio_stl_coords_t v3;
uint16_t attribute_byte_count; /*!< Useful only for STL binary format */
uint16_t attribute_byte_count; /*!< Useful only for STL binary format */
};
typedef struct gmio_stl_triangle gmio_stl_triangle_t;

12
src/gmio_support/occ_libstl.h
View File

@ -6,6 +6,10 @@
struct gmio_stl_mesh;
struct gmio_stl_mesh_creator;
/*! \brief Domain in a StlMesh_Mesh object
*
* The domain is indicated with its index within the STL mesh
*/
class GMIO_LIBSUPPORT_EXPORT gmio_OccStlMeshDomain
{
public:
@ -22,9 +26,17 @@ private:
int m_domainId;
};
/*! \brief Initializes \p mesh so it maps to a domain in StlMesh_Mesh
*
* \c mesh->cookie will point to \p meshCookie
*/
GMIO_LIBSUPPORT_EXPORT
void gmio_stl_occmesh(gmio_stl_mesh* mesh, const gmio_OccStlMeshDomain& meshCookie);
/*! \brief Initializes \p creator to build a new domain in a StlMesh_Mesh object
*
* \c creator->cookie will point to the internal data(ie. StlMesh_Mesh*) of handle \p mesh
*/
GMIO_LIBSUPPORT_EXPORT
void gmio_stl_occmesh_creator(gmio_stl_mesh_creator* creator, const Handle_StlMesh_Mesh& mesh);

2
src/gmio_support/qt_stream.h
View File

@ -5,6 +5,8 @@
struct gmio_stream;
class QIODevice;
/*! \brief Configures \p stream for \c QIODevice* (cookie will hold \p device)
*/
GMIO_LIBSUPPORT_EXPORT
void gmio_stream_set_qiodevice(struct gmio_stream* stream, QIODevice* device);