Extend @brief docs to 50+ chars

Change-Id: Ib2476119ada08d53c29fe75a472161107b1cbcda

diff --git a/include/peripheral_io.h b/include/peripheral_io.h
index 00c1cdf8aac24834627e069437876e6391b51382..27985c3284ec7614b5eb5b85875af534482fb915 100644 (file)
--- 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