From: Michal Bloch Date: Mon, 23 Sep 2024 07:18:40 +0000 (+0200) Subject: Extend @brief docs to 50+ chars X-Git-Tag: accepted/tizen/unified/20241001.004115~1 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=41b232e80f3571a74e38d5a263f7dea2462c30ea;p=platform%2Fcore%2Fapi%2Fperipheral-io.git Extend @brief docs to 50+ chars Change-Id: Ib2476119ada08d53c29fe75a472161107b1cbcda --- diff --git a/include/peripheral_io.h b/include/peripheral_io.h index 00c1cdf..27985c3 100644 --- a/include/peripheral_io.h +++ b/include/peripheral_io.h @@ -31,11 +31,11 @@ extern "C" { /** * @file peripheral_io.h - * @brief This file contains the peripheral-io API. + * @brief This file contains the public peripheral-io interface. */ /** - * @brief Enumeration for peripheral-io error. + * @brief Enumeration for error codes returned by the peripheral-io API. * @since_tizen 4.0 */ typedef enum { @@ -61,7 +61,7 @@ typedef enum { */ /** - * @brief Enumeration of GPIO direction options. + * @brief Enumeration representing GPIO device direction options. * @since_tizen 4.0 */ typedef enum { @@ -71,7 +71,7 @@ typedef enum { } peripheral_gpio_direction_e; /** - * @brief Enumeration of edge types for the GPIO interrupt. + * @brief Enumeration for edge types for the GPIO interrupt. * @since_tizen 4.0 */ typedef enum { @@ -82,14 +82,14 @@ typedef enum { } peripheral_gpio_edge_e; /** - * @brief The handle of a GPIO pin. + * @brief An opaque handle to an object representing a GPIO pin. * @since_tizen 4.0 */ typedef struct _peripheral_gpio_s *peripheral_gpio_h; /** * @platform - * @brief Opens a GPIO pin. + * @brief Opens a GPIO pin and returns a handle representing it * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -115,7 +115,7 @@ EXPORT_API int peripheral_gpio_open(int gpio_pin, peripheral_gpio_h *gpio); /** * @platform - * @brief Closes a GPIO pin. + * @brief Closes a GPIO pin and frees the resources associated with the handle * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -137,7 +137,7 @@ EXPORT_API int peripheral_gpio_close(peripheral_gpio_h gpio); /** * @platform - * @brief Sets the GPIO direction. + * @brief Sets the input/output direction of given GPIO pin. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -162,7 +162,7 @@ EXPORT_API int peripheral_gpio_set_direction(peripheral_gpio_h gpio, peripheral_ /** * @platform - * @brief Sets the GPIO edge mode. + * @brief Sets the input edge mode of given GPIO pin device. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -234,7 +234,7 @@ EXPORT_API int peripheral_gpio_set_interrupted_cb(peripheral_gpio_h gpio, periph /** * @platform - * @brief Unsets the GPIO interrupted callback. + * @brief Unsets the GPIO interrupted callback invoked when the GPIO interrupt is triggered. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -253,7 +253,7 @@ EXPORT_API int peripheral_gpio_unset_interrupted_cb(peripheral_gpio_h gpio); /** * @platform - * @brief Gets the current value of the GPIO pin. + * @brief Gets the current value being exposed on the GPIO pin. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -276,7 +276,7 @@ EXPORT_API int peripheral_gpio_read(peripheral_gpio_h gpio, uint32_t *value); /** * @platform - * @brief Sets the value of the GPIO pin. + * @brief Sets the value to be exposed on the given GPIO pin. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -309,14 +309,14 @@ EXPORT_API int peripheral_gpio_write(peripheral_gpio_h gpio, uint32_t value); */ /** - * @brief The handle of the I2C slave device. + * @brief An opaque handle representing the I2C slave device. * @since_tizen 4.0 */ typedef struct _peripheral_i2c_s *peripheral_i2c_h; /** * @platform - * @brief Opens an I2C slave device. + * @brief Opens an I2C slave device and returns a handle representing it * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -342,7 +342,7 @@ typedef struct _peripheral_i2c_s *peripheral_i2c_h; EXPORT_API int peripheral_i2c_open(int bus, int address, peripheral_i2c_h *i2c); /** - * @brief Enumeration for open flags (bitmask). + * @brief Enumeration for open flags (bitmask) for an i2c device. * @since_tizen 6.5 * * @remarks Enum values are supposed to be used as bitmask, where only one @@ -360,7 +360,7 @@ typedef enum { /** * @platform - * @brief Opens an I2C slave device. + * @brief Opens an I2C slave device and returns a representing handle * @since_tizen 6.5 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -388,7 +388,7 @@ EXPORT_API int peripheral_i2c_open_flags(int bus, int address, peripheral_open_f /** * @platform - * @brief Closes an I2C slave device. + * @brief Closes an I2C slave device and frees resources associated with the handle. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -408,7 +408,7 @@ EXPORT_API int peripheral_i2c_close(peripheral_i2c_h i2c); /** * @platform - * @brief Reads the bytes data from the I2C slave device. + * @brief Reads the bytes data from the I2C slave device into a buffer * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -431,7 +431,7 @@ EXPORT_API int peripheral_i2c_read(peripheral_i2c_h i2c, uint8_t *data, uint32_t /** * @platform - * @brief Writes the bytes data to the I2C slave device. + * @brief Writes the bytes data from a buffer to the I2C slave device. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -554,13 +554,13 @@ EXPORT_API int peripheral_i2c_write_register_word(peripheral_i2c_h i2c, uint8_t */ /** - * @brief The handle of the PWM peripherals. + * @brief An opaque handle representing a PWM peripherals pin. * @since_tizen 4.0 */ typedef struct _peripheral_pwm_s *peripheral_pwm_h; /** - * @brief Enumeration for Polarity. + * @brief Enumeration for representing PWN active signal Polarity. * @since_tizen 4.0 */ typedef enum { @@ -570,7 +570,7 @@ typedef enum { /** * @platform - * @brief Opens the PWM pin. + * @brief Opens the PWM pin and returns a handle representing it * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -597,7 +597,7 @@ EXPORT_API int peripheral_pwm_open(int chip, int pin, peripheral_pwm_h *pwm); /** * @platform - * @brief Closes the PWM pin. + * @brief Closes a PWM pin and frees resources associated with the handle. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -619,7 +619,7 @@ EXPORT_API int peripheral_pwm_close(peripheral_pwm_h pwm); /** * @platform - * @brief Sets period of the PWM pin. + * @brief Sets the period length in nanoseconds for the given PWM pin. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -640,7 +640,7 @@ EXPORT_API int peripheral_pwm_set_period(peripheral_pwm_h pwm, uint32_t period_n /** * @platform - * @brief Sets duty cycle of the PWM pin. + * @brief Sets the length of a duty cycle of the given PWM pin. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -661,7 +661,7 @@ EXPORT_API int peripheral_pwm_set_duty_cycle(peripheral_pwm_h pwm, uint32_t duty /** * @platform - * @brief Sets polarity of the PWM pin. + * @brief Sets the active signal polarity of the given PWM pin. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -684,7 +684,7 @@ EXPORT_API int peripheral_pwm_set_polarity(peripheral_pwm_h pwm, peripheral_pwm_ /** * @platform - * @brief Enables the PWM pin. + * @brief Toggles whether given PWM peripherals pin is enabled. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -713,14 +713,14 @@ EXPORT_API int peripheral_pwm_set_enabled(peripheral_pwm_h pwm, bool enabled); */ /** - * @brief The handle of the ADC peripherals. + * @brief An opaque handle representing an ADC peripherals pin. * @since_tizen 5.0 */ typedef struct _peripheral_adc_s *peripheral_adc_h; /** * @platform - * @brief Opens the ADC pin. + * @brief Opens the ADC pin and returns a handle representing it * @since_tizen 5.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -747,7 +747,7 @@ EXPORT_API int peripheral_adc_open(int device, int channel, peripheral_adc_h *ad /** * @platform - * @brief Closes the ADC pin. + * @brief Closes the ADC pin and frees the resources associated with it. * @since_tizen 5.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -769,7 +769,7 @@ EXPORT_API int peripheral_adc_close(peripheral_adc_h adc); /** * @platform - * @brief Gets the current value of the ADC pin. + * @brief Gets the current value of the ADC peripherals pin. * @since_tizen 5.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -799,13 +799,13 @@ EXPORT_API int peripheral_adc_read(peripheral_adc_h adc, uint32_t *value); */ /** - * @brief The handle to the UART peripherals. + * @brief An opaque handle representing a UART peripherals device. * @since_tizen 4.0 */ typedef struct _peripheral_uart_s *peripheral_uart_h; /** - * @brief Enumeration for baud rate. + * @brief Enumeration for signal baud rate for UART slave devices. * @since_tizen 4.0 */ typedef enum { @@ -831,7 +831,7 @@ typedef enum { } peripheral_uart_baud_rate_e; /** - * @brief Enumeration for byte size. + * @brief Enumeration for data byte size for UART slave devices. * @since_tizen 4.0 */ typedef enum { @@ -842,7 +842,7 @@ typedef enum { } peripheral_uart_byte_size_e; /** - * @brief Enumeration for parity bit. + * @brief Enumeration for parity bit for UART slave devices. * @since_tizen 4.0 */ typedef enum { @@ -852,7 +852,7 @@ typedef enum { } peripheral_uart_parity_e; /** - * @brief Enumeration for stop bits. + * @brief Enumeration for the number of stop bits for UART slave devices. * @since_tizen 4.0 */ typedef enum { @@ -861,7 +861,7 @@ typedef enum { } peripheral_uart_stop_bits_e; /** - * @brief Enumeration for hardware flow control. + * @brief Enumeration for hardware flow control for UART slave devices. * @since_tizen 4.0 */ typedef enum { @@ -870,7 +870,7 @@ typedef enum { } peripheral_uart_hardware_flow_control_e; /** - * @brief Enumeration for software flow control. + * @brief Enumeration for software flow control for UART slave devices. * @since_tizen 4.0 */ typedef enum { @@ -880,7 +880,7 @@ typedef enum { /** * @platform - * @brief Opens the UART slave device. + * @brief Opens the UART slave device and returns a handle representing it * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -906,7 +906,7 @@ EXPORT_API int peripheral_uart_open(int port, peripheral_uart_h *uart); /** * @platform - * @brief Opens the UART slave device. + * @brief Opens the UART slave device using specified open flags, and returns a handle representing it * @since_tizen 6.5 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -933,7 +933,7 @@ EXPORT_API int peripheral_uart_open_flags(int port, peripheral_open_flags_e flag /** * @platform - * @brief Closes the UART slave device. + * @brief Closes the UART slave device and frees resources associated with the handle. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -953,7 +953,7 @@ EXPORT_API int peripheral_uart_close(peripheral_uart_h uart); /** * @platform - * @brief Sets baud rate of the UART slave device. + * @brief Sets the baud rate for the given UART slave device. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -976,7 +976,7 @@ EXPORT_API int peripheral_uart_set_baud_rate(peripheral_uart_h uart, peripheral_ /** * @platform - * @brief Sets byte size of the UART slave device. + * @brief Sets data byte size for the given UART slave device. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -999,7 +999,7 @@ EXPORT_API int peripheral_uart_set_byte_size(peripheral_uart_h uart, peripheral_ /** * @platform - * @brief Sets parity bit of the UART slave device. + * @brief Sets the parity bit for the given UART slave device. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -1022,7 +1022,7 @@ EXPORT_API int peripheral_uart_set_parity(peripheral_uart_h uart, peripheral_uar /** * @platform - * @brief Sets stop bits of the UART slave device. + * @brief Sets the number of stop bits for the UART slave device. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -1045,7 +1045,7 @@ EXPORT_API int peripheral_uart_set_stop_bits(peripheral_uart_h uart, peripheral_ /** * @platform - * @brief Sets flow control of the UART slave device. + * @brief Sets hardware and software flow control of the UART slave device. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -1072,7 +1072,7 @@ EXPORT_API int peripheral_uart_set_flow_control(peripheral_uart_h uart, /** * @platform - * @brief Reads data from the UART slave device. + * @brief Reads data from the UART slave device into a local buffer. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -1139,7 +1139,7 @@ EXPORT_API int peripheral_uart_drain(peripheral_uart_h uart); /** * @platform - * @brief Writes data to the UART slave device. + * @brief Writes data from a buffer to the UART slave device. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -1171,13 +1171,13 @@ EXPORT_API int peripheral_uart_write(peripheral_uart_h uart, uint8_t *data, uint */ /** - * @brief The handle of a SPI peripherals. + * @brief An opaque handle representing a SPI peripherals slave device. * @since_tizen 4.0 */ typedef struct _peripheral_spi_s *peripheral_spi_h; /** - * @brief Enumeration of SPI transfer modes. + * @brief Enumeration of transfer modes for SPI slave devices. * @since_tizen 4.0 */ typedef enum { @@ -1188,7 +1188,7 @@ typedef enum { } peripheral_spi_mode_e; /** - * @brief Enumeration of bit orders. + * @brief Enumeration of bit orders for SPI slave device interfaces. * @since_tizen 4.0 */ typedef enum { @@ -1198,7 +1198,7 @@ typedef enum { /** * @platform - * @brief Opens a SPI slave device. + * @brief Opens a SPI slave device and returns a handle representing it. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -1225,7 +1225,7 @@ EXPORT_API int peripheral_spi_open(int bus, int cs, peripheral_spi_h *spi); /** * @platform - * @brief Closes the SPI slave device. + * @brief Closes the SPI slave device and frees resources associated with the handle. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -1247,7 +1247,7 @@ EXPORT_API int peripheral_spi_close(peripheral_spi_h spi); /** * @platform - * @brief Sets the SPI transfer mode. + * @brief Sets the transfer mode for the given SPI slave device. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -1270,7 +1270,7 @@ EXPORT_API int peripheral_spi_set_mode(peripheral_spi_h spi, peripheral_spi_mode /** * @platform - * @brief Sets the SPI bit order. + * @brief Sets the transfer bit order for given SPI slave device. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -1294,7 +1294,7 @@ EXPORT_API int peripheral_spi_set_bit_order(peripheral_spi_h spi, peripheral_spi /** * @platform - * @brief Sets the number of bits per word. + * @brief Sets the number of bits per word for given SPI slave device. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -1315,7 +1315,7 @@ EXPORT_API int peripheral_spi_set_bits_per_word(peripheral_spi_h spi, uint8_t bi /** * @platform - * @brief Sets the frequency of the SPI bus. + * @brief Sets the board-dependent frequency of the SPI bus. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -1337,7 +1337,7 @@ EXPORT_API int peripheral_spi_set_frequency(peripheral_spi_h spi, uint32_t freq_ /** * @platform - * @brief Reads the bytes data from the SPI slave device. + * @brief Reads the bytes data from the SPI slave device to a local buffer. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -1361,7 +1361,7 @@ EXPORT_API int peripheral_spi_read(peripheral_spi_h spi, uint8_t *data, uint32_t /** * @platform - * @brief Writes the bytes data to the SPI slave device. + * @brief Writes the bytes data buffer to the SPI slave device. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio @@ -1385,7 +1385,7 @@ EXPORT_API int peripheral_spi_write(peripheral_spi_h spi, uint8_t *data, uint32_ /** * @platform - * @brief Exchanges the bytes data to the SPI slave device. + * @brief Exchanges (read and write) the bytes data to the SPI slave device. * @since_tizen 4.0 * @privlevel platform * @privilege http://tizen.org/privilege/peripheralio