1.1 --- a/src/cx/buffer.h Mon Dec 27 17:02:32 2021 +0100
1.2 +++ b/src/cx/buffer.h Mon Dec 27 17:16:32 2021 +0100
1.3 @@ -90,9 +90,9 @@
1.4 size_t size;
1.5 /**
1.6 * Flag register for buffer features.
1.7 - * \see #CX_BUFFER_DEFAULT
1.8 - * \see #CX_BUFFER_FREE_CONTENTS
1.9 - * \see #CX_BUFFER_AUTO_EXTEND
1.10 + * @see #CX_BUFFER_DEFAULT
1.11 + * @see #CX_BUFFER_FREE_CONTENTS
1.12 + * @see #CX_BUFFER_AUTO_EXTEND
1.13 */
1.14 int flags;
1.15 } cx_buffer_s;
1.16 @@ -109,11 +109,11 @@
1.17 * Then this function will allocate the space and enforce
1.18 * the #CX_BUFFER_FREE_CONTENTS flag.
1.19 *
1.20 - * \param space pointer to the memory area, or <code>NULL</code> to allocate
1.21 + * @param space pointer to the memory area, or <code>NULL</code> to allocate
1.22 * new memory
1.23 - * \param capacity the capacity of the buffer
1.24 - * \param flags buffer features (see cx_buffer_s.flags)
1.25 - * \return the new buffer
1.26 + * @param capacity the capacity of the buffer
1.27 + * @param flags buffer features (see cx_buffer_s.flags)
1.28 + * @return the new buffer
1.29 */
1.30 CxBuffer cxBufferCreate(
1.31 void *space,
1.32 @@ -127,7 +127,7 @@
1.33 * If the #CX_BUFFER_FREE_CONTENTS feature is enabled, the contents of the buffer
1.34 * are also freed.
1.35 *
1.36 - * \param buffer the buffer to destroy
1.37 + * @param buffer the buffer to destroy
1.38 */
1.39 void cxBufferDestroy(CxBuffer buffer);
1.40
1.41 @@ -136,11 +136,11 @@
1.42 *
1.43 * \note The #CX_BUFFER_FREE_CONTENTS feature is enforced for the new buffer.
1.44 *
1.45 - * \param src the source buffer
1.46 - * \param start the start position of extraction
1.47 - * \param length the count of bytes to extract (must not be zero)
1.48 - * \param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled)
1.49 - * \return a new buffer containing the extraction
1.50 + * @param src the source buffer
1.51 + * @param start the start position of extraction
1.52 + * @param length the count of bytes to extract (must not be zero)
1.53 + * @param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled)
1.54 + * @return a new buffer containing the extraction
1.55 */
1.56 CxBuffer cxBufferExtract(
1.57 CxBuffer src,
1.58 @@ -152,9 +152,9 @@
1.59 /**
1.60 * A shorthand macro for copying an entire buffer.
1.61 *
1.62 - * \param src the source buffer
1.63 - * \param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled)
1.64 - * \return a new buffer with the copied content
1.65 + * @param src the source buffer
1.66 + * @param flags features for the new buffer (#CX_BUFFER_FREE_CONTENTS will always be enabled)
1.67 + * @return a new buffer with the copied content
1.68 */
1.69 #define cxBufferClone(src, flags) cxBufferExtract(src, 0, (src)->capacity, flags)
1.70
1.71 @@ -181,16 +181,16 @@
1.72 * \note For situations where \c off_t is not large enough, there are specialized cxBufferShiftLeft() and
1.73 * cxBufferShiftRight() functions using a \c size_t as parameter type.
1.74 *
1.75 - * \par Security Note
1.76 - * The shifting operation does \em not erase the previously occupied memory cells.
1.77 - * You can easily do that manually, e.g. by calling
1.78 + * \attention
1.79 + * Security Note: The shifting operation does \em not erase the previously occupied memory cells.
1.80 + * But you can easily do that manually, e.g. by calling
1.81 * <code>memset(buffer->bytes, 0, shift)</code> for a right shift or
1.82 * <code>memset(buffer->size, 0, buffer->capacity - buffer->size)</code>
1.83 * for a left shift.
1.84 *
1.85 - * \param buffer the buffer
1.86 - * \param shift the shift offset (negative means left shift)
1.87 - * \return 0 on success, non-zero if a required auto-extension fails
1.88 + * @param buffer the buffer
1.89 + * @param shift the shift offset (negative means left shift)
1.90 + * @return 0 on success, non-zero if a required auto-extension fails
1.91 */
1.92 int cxBufferShift(
1.93 CxBuffer buffer,
1.94 @@ -201,10 +201,10 @@
1.95 * Shifts the buffer to the right.
1.96 * See cxBufferShift() for details.
1.97 *
1.98 - * \param buffer the buffer
1.99 - * \param shift the shift offset
1.100 - * \return 0 on success, non-zero if a required auto-extension fails
1.101 - * \see cxBufferShift()
1.102 + * @param buffer the buffer
1.103 + * @param shift the shift offset
1.104 + * @return 0 on success, non-zero if a required auto-extension fails
1.105 + * @see cxBufferShift()
1.106 */
1.107 int cxBufferShiftRight(
1.108 CxBuffer buffer,
1.109 @@ -218,10 +218,10 @@
1.110 * \note Since a left shift cannot fail due to memory allocation problems, this
1.111 * function always returns zero.
1.112 *
1.113 - * \param buffer the buffer
1.114 - * \param shift the positive shift offset
1.115 - * \return always zero
1.116 - * \see cxBufferShift()
1.117 + * @param buffer the buffer
1.118 + * @param shift the positive shift offset
1.119 + * @return always zero
1.120 + * @see cxBufferShift()
1.121 */
1.122 int cxBufferShiftLeft(
1.123 CxBuffer buffer,
1.124 @@ -242,10 +242,10 @@
1.125 * (\c SEEK_SET), the buffer size (\c SEEK_END) or leaves the buffer position
1.126 * unchanged (\c SEEK_CUR).
1.127 *
1.128 - * \param buffer the buffer
1.129 - * \param offset position offset relative to \p whence
1.130 - * \param whence one of \c SEEK_SET, \c SEEK_CUR or \c SEEK_END
1.131 - * \return 0 on success, non-zero if the position is invalid
1.132 + * @param buffer the buffer
1.133 + * @param offset position offset relative to \p whence
1.134 + * @param whence one of \c SEEK_SET, \c SEEK_CUR or \c SEEK_END
1.135 + * @return 0 on success, non-zero if the position is invalid
1.136 *
1.137 */
1.138 int cxBufferSeek(
1.139 @@ -259,7 +259,7 @@
1.140 *
1.141 * The data is deleted by zeroing it with a call to memset().
1.142 *
1.143 - * \param buffer the buffer to be cleared
1.144 + * @param buffer the buffer to be cleared
1.145 */
1.146 #define cxBufferClear(buffer) memset((buffer)->bytes, 0, (buffer)->size); \
1.147 (buffer)->size = 0; (buffer)->pos = 0;
1.148 @@ -267,8 +267,8 @@
1.149 /**
1.150 * Tests, if the buffer position has exceeded the buffer capacity.
1.151 *
1.152 - * \param buffer the buffer to test
1.153 - * \return non-zero, if the current buffer position has exceeded the last
1.154 + * @param buffer the buffer to test
1.155 + * @return non-zero, if the current buffer position has exceeded the last
1.156 * available byte of the buffer.
1.157 */
1.158 int cxBufferEof(CxBuffer buffer);
1.159 @@ -279,9 +279,9 @@
1.160 *
1.161 * If the current capacity is not sufficient, the buffer will be extended.
1.162 *
1.163 - * \param buffer the buffer
1.164 - * \param capacity the minimum required capacity for this buffer
1.165 - * \return 0 on success or a non-zero value on failure
1.166 + * @param buffer the buffer
1.167 + * @param capacity the minimum required capacity for this buffer
1.168 + * @return 0 on success or a non-zero value on failure
1.169 */
1.170 int cxBufferMinimumCapacity(
1.171 CxBuffer buffer,
1.172 @@ -295,11 +295,11 @@
1.173 *
1.174 * \note The signature is compatible with the fwrite() family of functions.
1.175 *
1.176 - * \param ptr a pointer to the memory area containing the bytes to be written
1.177 - * \param size the length of one element
1.178 - * \param nitems the element count
1.179 - * \param buffer the CxBuffer to write to
1.180 - * \return the total count of bytes written
1.181 + * @param ptr a pointer to the memory area containing the bytes to be written
1.182 + * @param size the length of one element
1.183 + * @param nitems the element count
1.184 + * @param buffer the CxBuffer to write to
1.185 + * @return the total count of bytes written
1.186 */
1.187 size_t cxBufferWrite(
1.188 const void *ptr,
1.189 @@ -315,11 +315,11 @@
1.190 *
1.191 * \note The signature is compatible with the fread() family of functions.
1.192 *
1.193 - * \param ptr a pointer to the memory area where to store the read data
1.194 - * \param size the length of one element
1.195 - * \param nitems the element count
1.196 - * \param buffer the CxBuffer to read from
1.197 - * \return the total number of elements read
1.198 + * @param ptr a pointer to the memory area where to store the read data
1.199 + * @param size the length of one element
1.200 + * @param nitems the element count
1.201 + * @param buffer the CxBuffer to read from
1.202 + * @return the total number of elements read
1.203 */
1.204 size_t cxBufferRead(
1.205 void *ptr,
1.206 @@ -338,9 +338,9 @@
1.207 *
1.208 * On successful write, the position of the buffer is increased.
1.209 *
1.210 - * \param buffer the buffer to write to
1.211 - * \param c the character to write
1.212 - * \return the byte that has bean written or \c EOF when the end of the stream is
1.213 + * @param buffer the buffer to write to
1.214 + * @param c the character to write
1.215 + * @return the byte that has bean written or \c EOF when the end of the stream is
1.216 * reached and automatic extension is not enabled or not possible
1.217 */
1.218 int cxBufferPut(
1.219 @@ -353,17 +353,17 @@
1.220 *
1.221 * The current position of the buffer is increased after a successful read.
1.222 *
1.223 - * \param buffer the buffer to read from
1.224 - * \return the character or \c EOF, if the end of the buffer is reached
1.225 + * @param buffer the buffer to read from
1.226 + * @return the character or \c EOF, if the end of the buffer is reached
1.227 */
1.228 int cxBufferGet(CxBuffer buffer);
1.229
1.230 /**
1.231 * Writes a string to a buffer.
1.232 *
1.233 - * \param buffer the buffer
1.234 - * \param str the zero-terminated string
1.235 - * \return the number of bytes written
1.236 + * @param buffer the buffer
1.237 + * @param str the zero-terminated string
1.238 + * @return the number of bytes written
1.239 */
1.240 size_t cxBufferPutString(
1.241 CxBuffer buffer,
