ucx: comparison src/cx/properties.h

-:5c16dc362684
+:0480f8600fb7
 * 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.
 */
 /**
-* \file properties.h
+* @file properties.h
-* \brief Interface for parsing data from properties files.
+* @brief Interface for parsing data from properties files.
-* \author Mike Becker
+* @author Mike Becker
-* \author Olaf Wintermann
+* @author Olaf Wintermann
-* \copyright 2-Clause BSD License
+* @copyright 2-Clause BSD License
 */
 #ifndef UCX_PROPERTIES_H
 #define UCX_PROPERTIES_H
 CX_PROPERTIES_INCOMPLETE_DATA,
 /**
 * Not used as a status and never returned by any function.
 *
 * You can use this enumerator to check for all "good" status results
-* by checking if the status is less than \c CX_PROPERTIES_OK.
+* by checking if the status is less than @c CX_PROPERTIES_OK.
 *
 * A "good" status means, that you can refill data and continue parsing.
 */
 CX_PROPERTIES_OK,
 /**
-* Input buffer is \c NULL.
+* Input buffer is @c NULL.
 */
 CX_PROPERTIES_NULL_INPUT,
 /**
 * The line contains a delimiter, but no key.
 */
 *
 * @param prop the properties interface that wants to sink a k/v-pair
 * @param sink the sink
 * @param key the key
 * @param value the value
-* @return zero on success, non-zero when sinking the k/v-pair failed
+* @retval zero success
+* @retval non-zero sinking the k/v-pair failed
 */
 cx_attr_nonnull
 typedef int(*cx_properties_sink_func)(
 CxProperties *prop,
 CxPropertiesSink *sink,
 /**
 * A function that reads data from a source.
 *
 * When the source is depleted, implementations SHALL provide an empty
-* string in the \p target and return zero.
+* string in the @p target and return zero.
 * A non-zero return value is only permitted in case of an error.
 *
 * The meaning of the optional parameters is implementation-dependent.
 *
 * @param prop the properties interface that wants to read from the source
 * @param src the source
 * @param target a string buffer where the read data shall be stored
-* @return zero on success, non-zero when reading data failed
+* @retval zero success
+* @retval non-zero reading the data failed
 */
 cx_attr_nonnull
 typedef int(*cx_properties_read_func)(
 CxProperties *prop,
 CxPropertiesSource *src,
 /**
 * A function that may initialize additional memory for the source.
 *
 * @param prop the properties interface that wants to read from the source
 * @param src the source
-* @return zero when initialization was successful, non-zero otherwise
+* @retval zero initialization was successful
+* @retval non-zero otherwise
 */
 cx_attr_nonnull
 typedef int(*cx_properties_read_init_func)(
 CxProperties *prop,
 CxPropertiesSource *src
 void cxPropertiesInit(CxProperties *prop, CxPropertiesConfig config);
 /**
 * Destroys the properties interface.
 *
-* \note Even when you are certain that you did not use the interface in a
+* @note Even when you are certain that you did not use the interface in a
 * way that caused a memory allocation, you should call this function anyway.
 * Future versions of the library might add features that need additional memory
 * and you really don't want to search the entire code where you might need
 * add call to this function.
 *
 }
 /**
 * Initialize a properties parser with the default configuration.
 *
-* @param prop the properties interface
+* @param prop (@c CxProperties*) the properties interface
 * @see cxPropertiesInit()
 */
 #define cxPropertiesInitDefault(prop) \
 cxPropertiesInit(prop, cx_properties_config_default)
 * an allocation of a new buffer and copying the previous contents.
 *
 * @param prop the properties interface
 * @param buf a pointer to the data
 * @param len the length of the data
-* @return non-zero when a memory allocation was necessary but failed
+* @retval zero success
+* @retval non-zero a memory allocation was necessary but failed
 * @see cxPropertiesFill()
 */
 cx_attr_nonnull
 cx_attr_access_r(2, 3)
 int cxPropertiesFilln(
 * the additional data is appended - inevitably leading to
 * an allocation of a new buffer and copying the previous contents.
 *
 * @param prop the properties interface
 * @param str the text to fill in
-* @return non-zero when a memory allocation was necessary but failed
+* @retval zero success
+* @retval non-zero a memory allocation was necessary but failed
 * @see cxPropertiesFilln()
 */
 #define cxPropertiesFill(prop, str) _Generic((str), \
 cxstring: cx_properties_fill_cxstr,             \
 cxmutstr: cx_properties_fill_mutstr,            \
 * If no more key/value-pairs are found, #CX_PROPERTIES_NO_DATA is returned.
 *
 * When an incomplete line is encountered, #CX_PROPERTIES_INCOMPLETE_DATA is
 * returned, and you can add more data with #cxPropertiesFill().
 *
-* \remark The incomplete line will be stored in an internal buffer, which is
+* @remark The incomplete line will be stored in an internal buffer, which is
 * allocated on the heap, by default. If you want to avoid allocations,
 * you can specify sufficient space with cxPropertiesUseStack() after
 * initialization with cxPropertiesInit().
 *
-* \attention The returned strings will point into a buffer that might not be
+* @attention The returned strings will point into a buffer that might not be
 * available later. It is strongly recommended to copy the strings for further
 * use.
 *
 * @param prop the properties interface
 * @param key a pointer to the cxstring that shall contain the property name
 * @param value a pointer to the cxstring that shall contain the property value
-* @return the status code as defined above
+* @retval CX_PROPERTIES_NO_ERROR (zero) a key/value pair was found
-* @see cxPropertiesFill()
+* @retval CX_PROPERTIES_NO_DATA there is no (more) data in the input buffer
+* @retval CX_PROPERTIES_INCOMPLETE_DATA the data in the input buffer is incomplete
+* (fill more data and try again)
+* @retval CX_PROPERTIES_NULL_INPUT the input buffer was never filled
+* @retval CX_PROPERTIES_INVALID_EMPTY_KEY the properties data contains an illegal empty key
+* @retval CX_PROPERTIES_INVALID_MISSING_DELIMITER the properties data contains a line without delimiter
+* @retval CX_PROPERTIES_BUFFER_ALLOC_FAILED an internal allocation was necessary but failed
 */
 cx_attr_nonnull
 cx_attr_nodiscard
 CxPropertiesStatus cxPropertiesNext(
 CxProperties *prop,
 * Creates a properties sink for an UCX map.
 *
 * The values stored in the map will be pointers to strings allocated
 * by #cx_strdup_a().
 * The default stdlib allocator will be used, unless you specify a custom
-* allocator in the optional \c data of the sink.
+* allocator in the optional @c data of the sink.
 *
 * @param map the map that shall consume the k/v-pairs.
 * @return the sink
 * @see cxPropertiesLoad()
 */
 * The other result codes apply, according to their description.
 *
 * @param prop the properties interface
 * @param sink the sink
 * @param source the source
-* @return the status of the last operation
+* @retval CX_PROPERTIES_NO_ERROR (zero) a key/value pair was found
+* @retval CX_PROPERTIES_READ_INIT_FAILED initializing the source failed
+* @retval CX_PROPERTIES_READ_FAILED reading from the source failed
+* @retval CX_PROPERTIES_SINK_FAILED sinking the properties into the sink failed
+* @retval CX_PROPERTIES_NO_DATA the source did not provide any key/value pairs
+* @retval CX_PROPERTIES_INVALID_EMPTY_KEY the properties data contains an illegal empty key
+* @retval CX_PROPERTIES_INVALID_MISSING_DELIMITER the properties data contains a line without delimiter
+* @retval CX_PROPERTIES_BUFFER_ALLOC_FAILED an internal allocation was necessary but failed
 */
 cx_attr_nonnull
 CxPropertiesStatus cxPropertiesLoad(
 CxProperties *prop,
 CxPropertiesSink sink,

Mercurial > hg > ucx / file comparison

comparison: src/cx/properties.h

src/cx/properties.h