updated IODataReader interface for combined Serial and I2C;

pi4j-api/src/main/java/com/pi4j/io/IODataWriter.java

@@ -145,7 +145,7 @@ default int write(Collection<byte[]> data) throws IOException {
     /**
      * Write a buffer of byte values with given offset (starting position) and length in the provided data buffer.
      *
-     * NOTE:  The buffer's internal position tracking is no
+     * NOTE:  The buffer's internal position tracking is not
      *        used but rather only the explicit offset and
      *        length provided.  If the requested length is
      *        greater than the buffers capacity (minus offset)
@@ -483,6 +483,14 @@ default int write(Charset charset, Collection<char[]> data) throws IOException {
     /**
      * Writes an ASCII based character buffer with a given offset and length.
      *
+     * NOTE:  The buffer's internal position tracking is not
+     *        used but rather only the explicit offset and
+     *        length provided.  If the requested length is
+     *        greater than the buffers capacity (minus offset)
+     *        then the specified length will be ignored and
+     *        this function will only read the number of
+     *        characters up to the buffers' available space.
+     *
      * @param buffer ASCII character buffer used for data write
      * @param offset offset in data character array to start at
      * @param length number of character in character array to be written
@@ -496,6 +504,14 @@ default int write(CharBuffer buffer, int offset, int length) throws IOException
     /**
      * Writes an ASCII based character buffer starting at first index to a given length.
      *
+     * NOTE:  The contents from the character buffer is read
+     *        from the current position index up to the length
+     *        requested or up to the buffer's remaining limit;
+     *        whichever is is lower .  If the buffer's current
+     *        position is already at the buffer's limit, then we
+     *        will automatically flip the buffer to begin reading
+     *        data from the zero position up to the buffer's limit.
+     *
      * @param buffer ASCII character buffer used for data write
      * @param length number of character in character array to be written
      * @return The number of bytes (not characters) written, possibly zero
@@ -508,6 +524,14 @@ default int write(CharBuffer buffer, int length) throws IOException {
     /**
      * Writes an ASCII based character buffer.
      *
+     * NOTE:  The contents from the character buffer is read
+     *        from the current position index up to the buffer's
+     *        remaining limit.  If the buffer's current position
+     *        is already at the buffer's limit, then we will
+     *        automatically flip the buffer to begin reading
+     *        data from the zero position up to the buffer's
+     *        limit.
+     *
      * @param buffer ASCII character buffer used for data write
      * @return The number of bytes (not characters) written, possibly zero
      * @throws IOException thrown on write error
@@ -519,6 +543,14 @@ default int write(CharBuffer buffer) throws IOException {
     /**
      * Writes multiple ASCII based character buffers.
      *
+     * NOTE:  The contents from each character buffer is read
+     *        from the current position index up to the buffer's
+     *        remaining limit.  If the buffer's current position
+     *        is already at the buffer's limit, then we will
+     *        automatically flip the buffer to begin reading
+     *        data from the zero position up to the buffer's
+     *        limit.
+     *
      * @param buffer ASCII character buffer used for data write
      * @return The number of bytes (not characters) written, possibly zero
      * @throws IOException thrown on write error
@@ -531,7 +563,7 @@ default int write(CharBuffer ... buffer) throws IOException {
      * Writes a character buffer with a given offset and length
      * using a specified character set to encode the chars into bytes.
      *
-     * NOTE:  The buffer's internal position tracking is no
+     * NOTE:  The buffer's internal position tracking is not
      *        used but rather only the explicit offset and
      *        length provided.  If the requested length is
      *        greater than the buffers capacity (minus offset)

pi4j-api/src/main/java/com/pi4j/io/i2c/I2CRegister.java

@@ -57,6 +57,14 @@ default int address(){
      */
     void writeWord(int word) throws IOException;
 
+    /**
+     * Read a single word value (16-bit) to the I2C device register.
+     *
+     * @return If success, then returns 16-bit word value read from I2C register; else a negative error code.
+     * @throws IOException thrown on write error
+     */
+    int readWord() throws IOException, IOReadException;
+
     /**
      * Write a single word value (16-bit) to the I2C device register
      * and immediately reads back a 16-bit word value.