From 5113ffd3b0b3c761681456fae5ed554c2b35cc8d Mon Sep 17 00:00:00 2001 From: Loek Le Blansch Date: Sat, 22 Jun 2024 13:44:06 +0200 Subject: add i2ctcp to doxygen --- lib/i2ctcp/i2ctcpv1.h | 64 ++++++++++++++++++++++++++++++++++++--------------- lib/i2ctcp/readme.md | 25 -------------------- 2 files changed, 45 insertions(+), 44 deletions(-) delete mode 100644 lib/i2ctcp/readme.md (limited to 'lib/i2ctcp') diff --git a/lib/i2ctcp/i2ctcpv1.h b/lib/i2ctcp/i2ctcpv1.h index 799b668..d7bb29e 100644 --- a/lib/i2ctcp/i2ctcpv1.h +++ b/lib/i2ctcp/i2ctcpv1.h @@ -2,43 +2,69 @@ #include #include +#include #ifdef __cplusplus extern "C" { #endif -/** \brief I2C over TCP message (v1) */ -struct i2ctcp_msg { - uint16_t addr; //!< I^2^C address +/** + * \defgroup i2ctcp i2ctcp + * \brief I2C over TCP + * + * This library includes protocol (de)serialization functions for sending and + * receiving I2C messages over TCP. These functions are used by the \ref main + * "main controller" and the \ref pbc "puzzle box client (pbc)". This library + * does not include any puzzle bus specific code. + * + * mpack is used for the actual (de)serialization, and the functions in this + * library act as helpers for parsing from chunked data streams. + * + * To use these functions, include the following statement in your + * CMakeLists.txt: + * + * ```cmake + * # include pbdrv + * add_subdirectory(lib/i2ctcp) + * + * # link with executable + * target_link_libraries(main i2ctcp) + * ``` + * + * \{ + */ + +//! I2C over TCP message (v1) +typedef struct { + uint16_t addr; //!< I2C address char * data; //!< message content size_t length; //!< message size size_t _rdata; //!< \private remaining bytes to read until message is complete -}; -typedef struct i2ctcp_msg i2ctcp_msg_t; +} i2ctcp_msg_t; /** * \brief Read chunk of input stream, and store resulting message in \p target * * This function is called for each chunk of data from an input stream, and * will parse the next puzzle bus message into \p target. The input stream is - * assumed to only contain messages encoded by \p i2ctcp_write() + * assumed to only contain messages encoded by \c i2ctcp_write() * - * \param target pointer to struct that will contain the finished message data - * \param buf pointer to input stream data chunk - * \param buf_sz size of \p buf + * \param target Pointer to struct that will contain the finished message data + * \param buf Pointer to input stream data chunk + * \param buf_sz Size of \p buf * * \returns Integer representing amount of bytes required to finish message, or * -1 if the message header could not be read. If this function returns 0, the * message in \p target is complete. * - * \note target->data will automatically be allocated by this function, even if - * the message is not fully parsed. This variable must be `free()`d by the + * \note \p target->data will automatically be allocated by this function, even + * if the message is not fully parsed. This variable must be free'd by the * caller after each complete message to prevent memory leaks. */ int i2ctcp_read(i2ctcp_msg_t * target, const char * buf, size_t buf_sz); /** - * \brief reset the remaining message data counter + * \brief Reset the remaining message data counter * * Calling this function has the effect of forcing \c i2ctcp_read() to parse * the next buffer chunk as the start of a new message. This function may be @@ -52,16 +78,16 @@ void i2ctcp_read_reset(i2ctcp_msg_t * target); * * This function allocates a buffer large enough to fit the message specified * in \p target, and encodes the data in \p target in a format that can be - * decoded later using \p i2ctcp_read() + * decoded later using \c i2ctcp_read(). * - * \param target pointer to struct that contains the message data - * \param buf pointer to \c char* that will contain the formatted message - * \param buf_sz pointer to \c size_t that will represent the final size of \p buf + * \param target Pointer to struct that contains the message data + * \param buf Pointer to \c char* that will contain the formatted message + * \param buf_sz Pointer to \c size_t that will represent the final size of \p buf * - * \returns boolean true if a the message could be encoded successfully, false - * if there was some kind of error + * \returns Boolean \c true if a the message could be encoded successfully, \c + * false if there was some kind of error * - * \note the pointer stored in \p buf must be `free()`d by the caller afterwards + * \note The pointer stored in \p buf must be free'd by the caller afterwards */ bool i2ctcp_write(const i2ctcp_msg_t * target, char ** buf, size_t * buf_sz); diff --git a/lib/i2ctcp/readme.md b/lib/i2ctcp/readme.md deleted file mode 100644 index d5bfe6d..0000000 --- a/lib/i2ctcp/readme.md +++ /dev/null @@ -1,25 +0,0 @@ -# i2ctcp (I2C over TCP) - -This folder includes protocol (de)serialization functions for sending and -receiving I2C messages over TCP. These functions are used by the -[main controller](../main) and the [puzzle box client (pbc)](../client). This -folder does not include any puzzle bus specific code, and the headers for -puzbus are in the [shared](../shared) folder instead. - -[MessagePack][msgpack] (specifically the [mpack][mpack] implementation) is used -for the actual serialization/deserializtion, and the functions in this folder -act as helpers for parsing from chunked data streams. - -To use these functions, include the following statement in your CMakeLists.txt: -```cmake -include(../i2ctcp/include.cmake) -``` - -The functions are available by `#include`ing the `i2ctcpv1.h` header, and are -extensively documented using Doxygen-style comments. - -[msgpack]: https://msgpack.org/ -[mpack]: https://github.com/ludocode/mpack/ - - - -- cgit v1.2.3