Merge pull request #8519 from cmonr/rollup

Rollup PR - UK Docathon pt1

Author: Cruz Monrreal

drivers/I2CSlave.h

@@ -25,38 +25,41 @@
 namespace mbed {
 /** \addtogroup drivers */
 
-/** An I2C Slave, used for communicating with an I2C Master device
+/** An I2C Slave, used for communicating with an I2C Master device.
  *
  * @note Synchronization level: Not protected
  *
- * Example:
+ * Example Simple I2C responder:
  * @code
- * // Simple I2C responder
  * #include <mbed.h>
  *
- * I2CSlave slave(p9, p10);
+ * const int SLAVE_ADDRESS = 0xA0;
+ * const char message[] = "Slave!";
  *
- * int main() {
- *     char buf[10];
- *     char msg[] = "Slave!";
+ * I2CSlave slave(I2C_SDA, I2C_SCL);
  *
- *     slave.address(0xA0);
+ * int main() {
+ *     slave.address(SLAVE_ADDRESS);
  *     while (1) {
- *         int i = slave.receive();
- *         switch (i) {
+ *         int operation = slave.receive();
+ *         switch (operation) {
  *             case I2CSlave::ReadAddressed:
- *                 slave.write(msg, strlen(msg) + 1); // Includes null char
+ *                 int status = slave.write(message, sizeof(message));
+ *                 if (status == 0) {
+ *                     printf("Written message: %s\n", message);
+ *                 } else {
+ *                     printf("Failed to write message.\n");
+ *                 }
  *                 break;
  *             case I2CSlave::WriteGeneral:
- *                 slave.read(buf, 10);
- *                 printf("Read G: %s\n", buf);
+ *                 int byte_read = slave.read();
+ *                 printf("Read General: %c (%d)\n", byte_read, byte_read);
  *                 break;
  *             case I2CSlave::WriteAddressed:
- *                 slave.read(buf, 10);
- *                 printf("Read A: %s\n", buf);
+ *                 int byte_read = slave.read();
+ *                 printf("Read Addressed: %c (%d)\n", byte_read, byte_read);
  *                 break;
  *         }
- *         for(int i = 0; i < 10; i++) buf[i] = 0;    // Clear buffer
  *     }
  * }
  * @endcode
@@ -74,71 +77,71 @@ class I2CSlave {
 
     /** Create an I2C Slave interface, connected to the specified pins.
      *
-     *  @param sda I2C data line pin
-     *  @param scl I2C clock line pin
+     *  @param sda I2C data line pin.
+     *  @param scl I2C clock line pin.
      */
     I2CSlave(PinName sda, PinName scl);
 
-    /** Set the frequency of the I2C interface
+    /** Set the frequency of the I2C interface.
      *
-     *  @param hz The bus frequency in hertz
+     *  @param hz The bus frequency in Hertz.
      */
     void frequency(int hz);
 
-    /** Checks to see if this I2C Slave has been addressed.
+    /** Check if this I2C Slave has been addressed.
      *
-     *  @returns
-     *  A status indicating if the device has been addressed, and how
-     *  - NoData            - the slave has not been addressed
-     *  - ReadAddressed     - the master has requested a read from this slave
-     *  - WriteAddressed    - the master is writing to this slave
-     *  - WriteGeneral      - the master is writing to all slave
+     *  @return A status indicating if the device has been addressed and how.
+     *  @retval NoData          The slave has not been addressed.
+     *  @retval ReadAddressed   The master has requested a read from this slave.
+     *  @retval WriteAddressed  The master is writing to this slave.
+     *  @retval WriteGeneral    The master is writing to all slave.
      */
     int receive(void);
 
-    /** Read from an I2C master.
+    /** Read specified number of bytes from an I2C master.
      *
-     *  @param data pointer to the byte array to read data in to
-     *  @param length maximum number of bytes to read
+     *  @param data   Pointer to the buffer to read data into.
+     *  @param length Number of bytes to read.
      *
-     *  @returns
-     *       0 on success,
-     *   non-0 otherwise
+     *  @return Result of the operation.
+     *  @retval 0       If the number of bytes read is equal to length requested.
+     *  @retval nonzero On error or if the number of bytes read is less than requested.
      */
     int read(char *data, int length);
 
     /** Read a single byte from an I2C master.
      *
-     *  @returns
-     *    the byte read
+     *  @return The byte read.
      */
     int read(void);
 
     /** Write to an I2C master.
      *
-     *  @param data pointer to the byte array to be transmitted
-     *  @param length the number of bytes to transmite
+     *  @param data   Pointer to the buffer containing the data to be sent.
+     *  @param length Number of bytes to send.
      *
-     *  @returns
-     *       0 on success,
-     *   non-0 otherwise
+     *  @return
+     *  @retval 0       If written all bytes successfully.
+     *  @retval nonzero On error or if the number of bytes written is less than requested.
      */
     int write(const char *data, int length);
 
     /** Write a single byte to an I2C master.
      *
-     *  @param data the byte to write
+     *  @param data Value to write.
      *
-     *  @returns
-     *    '1' if an ACK was received,
-     *    '0' otherwise
+     *  @return Result of the operation.
+     *  @retval 0 If a NACK is received.
+     *  @retval 1 If an ACK is received.
+     *  @retval 2 On timeout.
      */
     int write(int data);
 
-    /** Sets the I2C slave address.
+    /** Set the I2C slave address.
+     *
+     *  @param address The address to set for the slave (least significant bit is ignored).
      *
-     *  @param address The address to set for the slave (ignoring the least
-     *  signifcant bit). If set to 0, the slave will only respond to the
+     *  @note If address is set to 0, the slave will only respond to the
      *  general call address.
      */
     void address(int address);
@@ -147,8 +150,13 @@ class I2CSlave {
      */
     void stop(void);
 
+#if !defined(DOXYGEN_ONLY)
+
 protected:
+    /* Internal i2c object identifying the resources */
     i2c_t _i2c;
+
+#endif //!defined(DOXYGEN_ONLY)
 };
 
 } // namespace mbed

drivers/SPISlave.h

@@ -26,19 +26,18 @@
 namespace mbed {
 /** \addtogroup drivers */
 
-/** A SPI slave, used for communicating with a SPI Master device
+/** A SPI slave, used for communicating with a SPI master device.
  *
- * The default format is set to 8-bits, mode 0, and a clock frequency of 1MHz
+ * The default format is set to 8 bits, mode 0 and a clock frequency of 1MHz.
  *
  * @note Synchronization level: Not protected
  *
- * Example:
+ * Example of how to reply to a SPI master as slave:
  * @code
- * // Reply to a SPI master as slave
  *
  * #include "mbed.h"
  *
- * SPISlave device(p5, p6, p7, p8); // mosi, miso, sclk, ssel
+ * SPISlave device(SPI_MOSI, SPI_MISO, SPI_SCLK, SPI_CS);
  *
  * int main() {
  *     device.reply(0x00);              // Prime SPI with first reply
@@ -57,21 +56,21 @@ class SPISlave : private NonCopyable<SPISlave> {
 
 public:
 
-    /** Create a SPI slave connected to the specified pins
+    /** Create a SPI slave connected to the specified pins.
      *
-     *  mosi or miso can be specified as NC if not used
+     *  @note Either mosi or miso can be specified as NC if not used.
      *
-     *  @param mosi SPI Master Out, Slave In pin
-     *  @param miso SPI Master In, Slave Out pin
-     *  @param sclk SPI Clock pin
-     *  @param ssel SPI chip select pin
+     *  @param mosi SPI Master Out, Slave In pin.
+     *  @param miso SPI Master In, Slave Out pin.
+     *  @param sclk SPI Clock pin.
+     *  @param ssel SPI Chip Select pin.
      */
     SPISlave(PinName mosi, PinName miso, PinName sclk, PinName ssel);
 
-    /** Configure the data transmission format
+    /** Configure the data transmission format.
      *
-     *  @param bits Number of bits per SPI frame (4 - 16)
-     *  @param mode Clock polarity and phase mode (0 - 3)
+     *  @param bits Number of bits per SPI frame (4 - 16).
+     *  @param mode Clock polarity and phase mode (0 - 3).
      *
      * @code
      * mode | POL PHA
@@ -84,40 +83,47 @@ class SPISlave : private NonCopyable<SPISlave> {
      */
     void format(int bits, int mode = 0);
 
-    /** Set the spi bus clock frequency
+    /** Set the SPI bus clock frequency.
      *
-     *  @param hz SCLK frequency in hz (default = 1MHz)
+     *  @param hz Clock frequency in hz (default = 1MHz).
      */
     void frequency(int hz = 1000000);
 
-    /** Polls the SPI to see if data has been received
+    /** Polls the SPI to see if data has been received.
      *
-     *  @returns
-     *    0 if no data,
-     *    1 otherwise
+     *  @return Presence of received data.
+     *  @retval 0 No data waiting.
+     *  @retval 1 Data waiting.
      */
     int receive(void);
 
-    /** Retrieve  data from receive buffer as slave
+    /** Retrieve data from receive buffer as slave.
      *
-     *  @returns
-     *    the data in the receive buffer
+     *  @return The data in the receive buffer.
      */
     int read(void);
 
     /** Fill the transmission buffer with the value to be written out
      *  as slave on the next received message from the master.
      *
-     *  @param value the data to be transmitted next
+     *  @param value The data to be transmitted next.
      */
     void reply(int value);
 
+#if !defined(DOXYGEN_ONLY)
+
 protected:
+    /* Internal SPI object identifying the resources */
     spi_t _spi;
 
+    /* How many bits in an SPI frame */
     int _bits;
+    /* Clock phase and polarity */
     int _mode;
+    /* Clock frequency */
     int _hz;
+
+#endif //!defined(DOXYGEN_ONLY)
 };
 
 } // namespace mbed

features/netsocket/SocketAddress.h

@@ -42,7 +42,7 @@ class SocketAddress {
      *
      *  @param stack    Network stack to use for DNS resolution
      *  @param host     Hostname to resolve
-     *  @param port     Optional 16-bit port
+     *  @param port     Optional 16-bit port, defaults to 0
      *  @deprecated
      *      Constructors hide possible errors. Replaced by
      *      NetworkInterface::gethostbyname.
@@ -57,24 +57,26 @@ class SocketAddress {
     }
 
     /** Create a SocketAddress from a raw IP address and port
+     * 
+     * To construct from a host name, use NetworkInterface::gethostbyname
      *
      *  @param addr     Raw IP address
-     *  @param port     Optional 16-bit port
+     *  @param port     Optional 16-bit port, defaults to 0
      */
     SocketAddress(nsapi_addr_t addr = nsapi_addr_t(), uint16_t port = 0);
 
     /** Create a SocketAddress from an IP address and port
      *
      *  @param addr     Null-terminated representation of the IP address
-     *  @param port     Optional 16-bit port
+     *  @param port     Optional 16-bit port, defaults to 0
      */
     SocketAddress(const char *addr, uint16_t port = 0);
 
     /** Create a SocketAddress from raw IP bytes, IP version, and port
      *
      *  @param bytes    Raw IP address in big-endian order
      *  @param version  IP address version, NSAPI_IPv4 or NSAPI_IPv6
-     *  @param port     Optional 16-bit port
+     *  @param port     Optional 16-bit port, defaults to 0
      */
     SocketAddress(const void *bytes, nsapi_version_t version, uint16_t port = 0);