# HG changeset patch # User Mike Becker # Date 1640621792 -3600 # Node ID 6a86ad3d8c03361e0923ba20001ca7682a9d42f6 # Parent 9e6900b1cf9d5944ce19a306c0e6dd6545b58860 use same doxygen style in all files also adds doxygen main page diff -r 9e6900b1cf9d -r 6a86ad3d8c03 src/cx/buffer.h --- a/src/cx/buffer.h Mon Dec 27 17:02:32 2021 +0100 +++ b/src/cx/buffer.h Mon Dec 27 17:16:32 2021 +0100 @@ -90,9 +90,9 @@ size_t size; /** * Flag register for buffer features. - * \see #CX_BUFFER_DEFAULT - * \see #CX_BUFFER_FREE_CONTENTS - * \see #CX_BUFFER_AUTO_EXTEND + * @see #CX_BUFFER_DEFAULT + * @see #CX_BUFFER_FREE_CONTENTS + * @see #CX_BUFFER_AUTO_EXTEND */ int flags; } cx_buffer_s; @@ -109,11 +109,11 @@ * Then this function will allocate the space and enforce * the #CX_BUFFER_FREE_CONTENTS flag. * - * \param space pointer to the memory area, or NULL to allocate + * @param space pointer to the memory area, or NULL to allocate * new memory - * \param capacity the capacity of the buffer - * \param flags buffer features (see cx_buffer_s.flags) - * \return the new buffer + * @param capacity the capacity of the buffer + * @param flags buffer features (see cx_buffer_s.flags) + * @return the new buffer */ CxBuffer cxBufferCreate( void *space, @@ -127,7 +127,7 @@ * If the #CX_BUFFER_FREE_CONTENTS feature is enabled, the contents of the buffer * are also freed. * - * \param buffer the buffer to destroy + * @param buffer the buffer to destroy */ void cxBufferDestroy(CxBuffer buffer); @@ -136,11 +136,11 @@ * * \note The #CX_BUFFER_FREE_CONTENTS feature is enforced for the new buffer. * - * \param src the source buffer - * \param start the start position of extraction - * \param length the count of bytes to extract (must not be zero) - * \param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled) - * \return a new buffer containing the extraction + * @param src the source buffer + * @param start the start position of extraction + * @param length the count of bytes to extract (must not be zero) + * @param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled) + * @return a new buffer containing the extraction */ CxBuffer cxBufferExtract( CxBuffer src, @@ -152,9 +152,9 @@ /** * A shorthand macro for copying an entire buffer. * - * \param src the source buffer - * \param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled) - * \return a new buffer with the copied content + * @param src the source buffer + * @param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled) + * @return a new buffer with the copied content */ #define cxBufferClone(src, flags) cxBufferExtract(src, 0, (src)->capacity, flags) @@ -181,16 +181,16 @@ * \note For situations where \c off_t is not large enough, there are specialized cxBufferShiftLeft() and * cxBufferShiftRight() functions using a \c size_t as parameter type. * - * \par Security Note - * The shifting operation does \em not erase the previously occupied memory cells. - * You can easily do that manually, e.g. by calling + * \attention + * Security Note: The shifting operation does \em not erase the previously occupied memory cells. + * But you can easily do that manually, e.g. by calling * memset(buffer->bytes, 0, shift) for a right shift or * memset(buffer->size, 0, buffer->capacity - buffer->size) * for a left shift. * - * \param buffer the buffer - * \param shift the shift offset (negative means left shift) - * \return 0 on success, non-zero if a required auto-extension fails + * @param buffer the buffer + * @param shift the shift offset (negative means left shift) + * @return 0 on success, non-zero if a required auto-extension fails */ int cxBufferShift( CxBuffer buffer, @@ -201,10 +201,10 @@ * Shifts the buffer to the right. * See cxBufferShift() for details. * - * \param buffer the buffer - * \param shift the shift offset - * \return 0 on success, non-zero if a required auto-extension fails - * \see cxBufferShift() + * @param buffer the buffer + * @param shift the shift offset + * @return 0 on success, non-zero if a required auto-extension fails + * @see cxBufferShift() */ int cxBufferShiftRight( CxBuffer buffer, @@ -218,10 +218,10 @@ * \note Since a left shift cannot fail due to memory allocation problems, this * function always returns zero. * - * \param buffer the buffer - * \param shift the positive shift offset - * \return always zero - * \see cxBufferShift() + * @param buffer the buffer + * @param shift the positive shift offset + * @return always zero + * @see cxBufferShift() */ int cxBufferShiftLeft( CxBuffer buffer, @@ -242,10 +242,10 @@ * (\c SEEK_SET), the buffer size (\c SEEK_END) or leaves the buffer position * unchanged (\c SEEK_CUR). * - * \param buffer the buffer - * \param offset position offset relative to \p whence - * \param whence one of \c SEEK_SET, \c SEEK_CUR or \c SEEK_END - * \return 0 on success, non-zero if the position is invalid + * @param buffer the buffer + * @param offset position offset relative to \p whence + * @param whence one of \c SEEK_SET, \c SEEK_CUR or \c SEEK_END + * @return 0 on success, non-zero if the position is invalid * */ int cxBufferSeek( @@ -259,7 +259,7 @@ * * The data is deleted by zeroing it with a call to memset(). * - * \param buffer the buffer to be cleared + * @param buffer the buffer to be cleared */ #define cxBufferClear(buffer) memset((buffer)->bytes, 0, (buffer)->size); \ (buffer)->size = 0; (buffer)->pos = 0; @@ -267,8 +267,8 @@ /** * Tests, if the buffer position has exceeded the buffer capacity. * - * \param buffer the buffer to test - * \return non-zero, if the current buffer position has exceeded the last + * @param buffer the buffer to test + * @return non-zero, if the current buffer position has exceeded the last * available byte of the buffer. */ int cxBufferEof(CxBuffer buffer); @@ -279,9 +279,9 @@ * * If the current capacity is not sufficient, the buffer will be extended. * - * \param buffer the buffer - * \param capacity the minimum required capacity for this buffer - * \return 0 on success or a non-zero value on failure + * @param buffer the buffer + * @param capacity the minimum required capacity for this buffer + * @return 0 on success or a non-zero value on failure */ int cxBufferMinimumCapacity( CxBuffer buffer, @@ -295,11 +295,11 @@ * * \note The signature is compatible with the fwrite() family of functions. * - * \param ptr a pointer to the memory area containing the bytes to be written - * \param size the length of one element - * \param nitems the element count - * \param buffer the CxBuffer to write to - * \return the total count of bytes written + * @param ptr a pointer to the memory area containing the bytes to be written + * @param size the length of one element + * @param nitems the element count + * @param buffer the CxBuffer to write to + * @return the total count of bytes written */ size_t cxBufferWrite( const void *ptr, @@ -315,11 +315,11 @@ * * \note The signature is compatible with the fread() family of functions. * - * \param ptr a pointer to the memory area where to store the read data - * \param size the length of one element - * \param nitems the element count - * \param buffer the CxBuffer to read from - * \return the total number of elements read + * @param ptr a pointer to the memory area where to store the read data + * @param size the length of one element + * @param nitems the element count + * @param buffer the CxBuffer to read from + * @return the total number of elements read */ size_t cxBufferRead( void *ptr, @@ -338,9 +338,9 @@ * * On successful write, the position of the buffer is increased. * - * \param buffer the buffer to write to - * \param c the character to write - * \return the byte that has bean written or \c EOF when the end of the stream is + * @param buffer the buffer to write to + * @param c the character to write + * @return the byte that has bean written or \c EOF when the end of the stream is * reached and automatic extension is not enabled or not possible */ int cxBufferPut( @@ -353,17 +353,17 @@ * * The current position of the buffer is increased after a successful read. * - * \param buffer the buffer to read from - * \return the character or \c EOF, if the end of the buffer is reached + * @param buffer the buffer to read from + * @return the character or \c EOF, if the end of the buffer is reached */ int cxBufferGet(CxBuffer buffer); /** * Writes a string to a buffer. * - * \param buffer the buffer - * \param str the zero-terminated string - * \return the number of bytes written + * @param buffer the buffer + * @param str the zero-terminated string + * @return the number of bytes written */ size_t cxBufferPutString( CxBuffer buffer, diff -r 9e6900b1cf9d -r 6a86ad3d8c03 src/cx/common.h --- a/src/cx/common.h Mon Dec 27 17:02:32 2021 +0100 +++ b/src/cx/common.h Mon Dec 27 17:16:32 2021 +0100 @@ -35,6 +35,46 @@ * \author Olaf Wintermann * \version 3.0 * \copyright 2-Clause BSD License + * + * \mainpage UAP Common Extensions + * Library with common and useful functions, macros and data structures. + *

+ * Latest available source:
+ * https://sourceforge.net/projects/ucx/files/ + *

+ * + *

+ * Repositories:
+ * https://sourceforge.net/p/ucx/code + * - or - + * https://develop.uap-core.de/hg/ucx + *

+ * + *

LICENCE

+ * + * Copyright 2021 Mike Becker, Olaf Wintermann All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef UCX_COMMON_H diff -r 9e6900b1cf9d -r 6a86ad3d8c03 src/cx/linked_list.h --- a/src/cx/linked_list.h Mon Dec 27 17:02:32 2021 +0100 +++ b/src/cx/linked_list.h Mon Dec 27 17:16:32 2021 +0100 @@ -138,6 +138,7 @@ * * @param node a pointer to a node in the list * @param loc_prev the location of the \c prev pointer + * @return a pointer to the first node */ void *cx_linked_list_first( void *node,