Add/tidy API doxygen for the new pico_i2c_slave library (#1233)

Author: andygpz11

src/rp2_common/pico_i2c_slave/include/pico/i2c_slave.h

@@ -15,12 +15,20 @@ extern "C" {
 #endif
 
 /** \file pico/i2c_slave.h
- * \defgrup pico_i2c_slave pico_i2c_slave
- * \brief I2C slave helper library, which takes care of hooking the I2C IRQ and calling back the user with I2C events.
+ * \defgroup pico_i2c_slave pico_i2c_slave
+ *
+ * Functions providing an interrupt driven I2C slave interface.
+ *
+ * This I2C slave helper library configures slave mode and hooks the relevant I2C IRQ
+ * so that a user supplied handler is called with enumerated I2C events.
+ *
+ * An example application \c slave_mem_i2c, which makes use of this library, can be found in 
+ * <a href="https://github.com/raspberrypi/pico-examples/blob/master/i2c/slave_mem_i2c/slave_mem_i2c.c">pico_examples</a>.
  */
 
 /**
  * \brief I2C slave event types.
+ * \ingroup pico_i2c_slave
  */
 typedef enum i2c_slave_event_t
 {
@@ -31,31 +39,32 @@ typedef enum i2c_slave_event_t
 
 /**
  * \brief I2C slave event handler
+ * \ingroup pico_i2c_slave
  * 
  * The event handler will run from the I2C ISR, so it should return quickly (under 25 us at 400 kb/s).
  * Avoid blocking inside the handler and split large data transfers across multiple calls for best results.
- * When sending data to master, up to `i2c_get_write_available()` bytes can be written without blocking.
- * When receiving data from master, up to `i2c_get_read_available()` bytes can be read without blocking.
- * 
- * \param i2c Slave I2C instance.
+ * When sending data to master, up to \ref i2c_get_write_available()  bytes can be written without blocking.
+ * When receiving data from master, up to \ref 2c_get_read_available() bytes can be read without blocking.
+ *
+ * \param i2c Either \ref i2c0 or \ref i2c1
  * \param event Event type.
  */
 typedef void (*i2c_slave_handler_t)(i2c_inst_t *i2c, i2c_slave_event_t event);
 
 /**
- * \brief Configure I2C instance for slave mode.
- * 
+ * \brief Configure an I2C instance for slave mode.
+ * \ingroup pico_i2c_slave
  * \param i2c I2C instance.
  * \param address 7-bit slave address.
- * \param handler Called on events from I2C master. It will run from the I2C ISR, on the CPU core
- *                where the slave was initialized.
+ * \param handler Callback for events from I2C master. It will run from the I2C ISR, on the CPU core
+ *                where the slave was initialised.
  */
 void i2c_slave_init(i2c_inst_t *i2c, uint8_t address, i2c_slave_handler_t handler);
 
 /**
- * \brief Restore I2C instance to master mode.
- *
- * \param i2c I2C instance.
+ * \brief Restore an I2C instance to master mode.
+ * \ingroup pico_i2c_slave
+ * \param i2c Either \ref i2c0 or \ref i2c1
  */
 void i2c_slave_deinit(i2c_inst_t *i2c);