I/O: Documentation changes

gohai · gohai · commit 1811de692871 · 2015-10-15T22:49:55.000+02:00
diff --git a/java/libraries/io/src/processing/io/GPIO.java b/java/libraries/io/src/processing/io/GPIO.java
@@ -89,14 +89,9 @@ public static void analogWrite(int pin, int value) {
 
 
   /**
-   *  Calls a function when the value of an INPUT pin changes
-   *
-   *  Don't use enableInterrupt() and waitForInterrupt() in combination with
-   *  this function, as they are orthogonal. The sketch method provided must
-   *  accept a single integer (int) parameter, which is the number of the GPIO
-   *  pin that the interrupt occured on.
+   *  Calls a function when the value of an input pin changes
    *  @param pin GPIO pin
-   *  @param parent this
+   *  @param parent typically use "this"
    *  @param method name of sketch method to call
    *  @param mode when to call: GPIO.CHANGE, GPIO.FALLING or GPIO.RISING
    *  @see noInterrupts
@@ -163,7 +158,6 @@ public void run() {
    *  Board-specific classes, such as RPI, assign -1 to pins that carry power,
    *  ground and the like.
    *  @param pin GPIO pin
-   *  @webref
    */
   protected static void checkValidPin(int pin) {
     if (pin < 0) {
@@ -174,9 +168,6 @@ protected static void checkValidPin(int pin) {
 
   /**
    *  Returns the value of an input pin
-   *
-   *  You need to set the pin to INPUT by calling pinMode before calling
-   *  this function.
    *  @param pin GPIO pin
    *  @return GPIO.HIGH (1) or GPIO.LOW (0)
    *  @see pinMode
@@ -207,14 +198,9 @@ public static int digitalRead(int pin) {
 
 
   /**
-   *  Sets an output pin to HIGH or LOW
-   *
-   *  You need set the pin to OUTPUT by calling pinMode before calling this
-   *  function. It is not possible to enable or disable internal pull-up
-   *  resistors for inputs using this function, which is something that's
-   *  supported on Arduino.
+   *  Sets an output pin to be either high or low
    *  @param pin GPIO pin
-   *  @param value GPIO.HIGH or GPIO.LOW
+   *  @param value GPIO.HIGH (1) or GPIO.LOW (0)
    *  @see pinMode
    *  @see digitalRead
    *  @webref
@@ -247,17 +233,7 @@ public static void digitalWrite(int pin, int value) {
 
 
   /**
-   *  Sets an output pin to HIGH or LOW
-   *
-   *  You need set the pin to OUTPUT by calling pinMode before calling this
-   *  function. It is not possible to enable or disable internal pull-up
-   *  resistors for inputs using this function, which is something that's
-   *  supported on Arduino.
-   *  @param pin GPIO pin
    *  @param value true or false
-   *  @see pinMode
-   *  @see digitalRead
-   *  @webref
    */
   public static void digitalWrite(int pin, boolean value) {
     if (value) {
@@ -269,33 +245,24 @@ public static void digitalWrite(int pin, boolean value) {
 
 
   /**
-   *  Disables an interrupt for an INPUT pin
-   *
-   *  Use this function only in combination with enableInterrupt() and
-   *  waitForInterrupt(). This should not be called when attachInterrupt()
-   *  is being used.
+   *  Disables an interrupt for an input pin
    *  @param pin GPIO pin
    *  @see enableInterrupt
    *  @see waitForInterrupt
-   *  @webref
    */
-  public static void disableInterrupt(int pin) {
+  protected static void disableInterrupt(int pin) {
     enableInterrupt(pin, NONE);
   }
 
 
   /**
-   *  Enables an interrupt for an INPUT pin
-   *
-   *  Use this function only when calling waitForInterrupt(). This should not
-   *  be called when attachInterrupt() is being used.
+   *  Enables an interrupt for an input pin
    *  @param pin GPIO pin
    *  @param mode what to wait for: GPIO.CHANGE, GPIO.FALLING or GPIO.RISING
    *  @see waitForInterrupt
    *  @see disableInterrupt
-   *  @webref
    */
-  public static void enableInterrupt(int pin, int mode) {
+  protected static void enableInterrupt(int pin, int mode) {
     checkValidPin(pin);
 
     String out;
@@ -324,11 +291,6 @@ public static void enableInterrupt(int pin, int mode) {
 
   /**
    *  Allows interrupts to happen
-   *
-   *  You can use noInterrupts() and interrupts() in tandem to make sure no interrupts
-   *  are occuring while your sketch is doing a particular task. This is only relevant
-   *  when using attachInterrupt(), not for waitForInterrupt(). By default, interrupts
-   *  are enabled.
    *  @see attachInterrupt
    *  @see noInterrupts
    *  @see releaseInterrupt
@@ -341,11 +303,6 @@ public static void interrupts() {
 
   /**
    *  Prevents interrupts from happpening
-   *
-   *  You can use noInterrupts() and interrupts() in tandem to make sure no interrupts
-   *  are occuring while your sketch is doing a particular task. This is only relevant
-   *  when using attachInterrupt(), not for waitForInterrupt(). By default, interrupts
-   *  are enabled.
    *  @see attachInterrupt
    *  @see interrupts
    *  @see releaseInterrupt
@@ -357,11 +314,7 @@ public static void noInterrupts() {
 
 
   /**
-   *  Sets a pin to INPUT or OUTPUT
-   *
-   *  While pins are implicitly set to input by default on Arduino, it is
-   *  necessary to call this function for any pin you want to access later,
-   *  including input pins.
+   *  Configures a pin to act either as input or output
    *  @param pin GPIO pin
    *  @param mode GPIO.INPUT or GPIO.OUTPUT
    *  @see digitalRead
@@ -421,10 +374,7 @@ public static void pinMode(int pin, int mode) {
 
 
   /**
-   *  Stops listening for interrupts on an INPUT pin
-   *
-   *  Use this function only in combination with attachInterrupt(). This should
-   *  not be called when enableInterrupt() and waitForInterrupt() are being used.
+   *  Stops listening for interrupts on an input pin
    *  @param pin GPIO pin
    *  @see attachInterrupt
    *  @see noInterrupts
@@ -452,9 +402,6 @@ public static void releaseInterrupt(int pin) {
 
   /**
    *  Gives ownership of a pin back to the operating system
-   *
-   *  Without calling this function the pin will remain in the current
-   *  state even after the sketch has been closed.
    *  @param pin GPIO pin
    *  @see pinMode
    *  @webref
@@ -477,7 +424,21 @@ public static void releasePin(int pin) {
 
 
   /**
-   *  Waits for the value of an INPUT pin to change
+   *  Waits for the value of an input pin to change
+   *  @param pin GPIO pin
+   *  @param mode what to wait for: GPIO.CHANGE, GPIO.FALLING or GPIO.RISING
+   *  @param timeout don't wait more than timeout milliseconds (-1 waits indefinitely)
+   *  @return true if the interrupt occured, false if the timeout occured
+   *  @webref
+   */
+  public static boolean waitForInterrupt(int pin, int mode, int timeout) {
+    enableInterrupt(pin, mode);
+    return waitForInterrupt(pin, timeout);
+  }
+
+
+  /**
+   *  Waits for the value of an input pin to change
    *
    *  Make sure to setup the interrupt with enableInterrupt() before calling
    *  this function. A timeout value of -1 waits indefinitely.
@@ -486,9 +447,8 @@ public static void releasePin(int pin) {
    *  @return true if the interrupt occured, false if the timeout occured
    *  @see enableInterrupt
    *  @see disableInterrupt
-   *  @webref
    */
-  public static boolean waitForInterrupt(int pin, int timeout) {
+  protected static boolean waitForInterrupt(int pin, int timeout) {
     checkValidPin(pin);
 
     String fn = String.format("/sys/class/gpio/gpio%d/value", pin);
@@ -509,17 +469,16 @@ public static boolean waitForInterrupt(int pin, int timeout) {
 
 
   /**
-   *  Waits for the value of an INPUT pin to change
+   *  Waits for the value of an input pin to change
    *
    *  Make sure to setup the interrupt with enableInterrupt() before calling
    *  this function. This function will wait indefinitely for an interrupt
    *  to occur.
    *  @parm pin GPIO pin
    *  @see enableInterrupt
    *  @see disableInterrupt
-   *  @webref
    */
-  public static void waitForInterrupt(int pin) {
+  protected static void waitForInterrupt(int pin) {
     waitForInterrupt(pin, -1);
   }
 }
diff --git a/java/libraries/io/src/processing/io/I2C.java b/java/libraries/io/src/processing/io/I2C.java
@@ -42,9 +42,8 @@ public class I2C {
 
 
   /**
-   *  Opens an I2C device as master
-   *
-   *  @param dev device name
+   *  Opens an I2C interface as master
+   *  @param dev interface name
    *  @see list
    *  @webref
    */
@@ -60,19 +59,6 @@ public I2C(String dev) {
 
   /**
    *  Begins a transmission to an attached device
-   *
-   *  I2C addresses consist of 7 bits plus one bit that indicates whether
-   *  the device is being read from or written to. Some datasheets list
-   *  the address in an 8 bit form (7 address bits + R/W bit), while others
-   *  provide the address in a 7 bit form, with the address in the lower
-   *  7 bits. This function expects the address in the lower 7 bits, the
-   *  same way as in Arduino's Wire library, and as shown in the output
-   *  of the i2cdetect tool.
-   *  If the address provided in a datasheet is greater than 127 (hex 0x7f)
-   *  or there are separate addresses for read and write operations listed,
-   *  which vary exactly by one, then you want to shift the this number by
-   *  one bit to the right before passing it as an argument to this function.
-   *  @param slave 7 bit address of slave device
    *  @see write
    *  @see read
    *  @see endTransmission
@@ -111,8 +97,6 @@ protected void finalize() throws Throwable {
 
   /**
    *  Ends the current transmissions
-   *
-   *  This executes any queued writes.
    *  @see beginTransmission
    *  @see write
    *  @webref
@@ -137,7 +121,7 @@ public void endTransmission() {
 
 
   /**
-   *  Lists all available I2C devices
+   *  Lists all available I2C interfaces
    *  @return String array
    *  @webref
    */
@@ -161,10 +145,6 @@ public static String[] list() {
 
   /**
    *  Reads bytes from the attached device
-   *
-   *  You must call beginTransmission() before calling this function. This function
-   *  also ends the current transmisison and sends any data that was queued using
-   *  write() before.
    *  @param len number of bytes to read
    *  @return bytes read from device
    *  @see beginTransmission
@@ -195,10 +175,6 @@ public byte[] read(int len) {
 
   /**
    *  Adds bytes to be written to the device
-   *
-   *  You must call beginTransmission() before calling this function.
-   *  The actual writing takes part when read() or endTransmission() is being
-   *  called.
    *  @param out bytes to be written
    *  @see beginTransmission
    *  @see read
@@ -222,33 +198,23 @@ public void write(byte[] out) {
 
 
   /**
-   *  Adds bytes to be written to the device
-   *
-   *  You must call beginTransmission() before calling this function.
-   *  The actual writing takes part when read() or endTransmission() is being
-   *  called.
+   *  Adds bytes to be written to the attached device
    *  @param out string to be written
    *  @see beginTransmission
    *  @see read
    *  @see endTransmission
-   *  @webref
    */
   public void write(String out) {
     write(out.getBytes());
   }
 
 
   /**
-   *  Adds a byte to be written to the device
-   *
-   *  You must call beginTransmission() before calling this function.
-   *  The actual writing takes part when read() or endTransmission() is being
-   *  called.
+   *  Adds a byte to be written to the attached device
    *  @param out single byte to be written (0-255)
    *  @see beginTransmission
    *  @see read
    *  @see endTransmission
-   *  @webref
    */
   public void write(int out) {
     if (out < 0 || 255 < out) {
diff --git a/java/libraries/io/src/processing/io/LED.java b/java/libraries/io/src/processing/io/LED.java
@@ -119,9 +119,6 @@ public void brightness(float bright) {
 
   /**
    *  Restores the previous state
-   *
-   *  Without calling this function the LED will remain in the current
-   *  state even after the sketch has been closed.
    *  @webref
    */
   public void close() {
diff --git a/java/libraries/io/src/processing/io/PWM.java b/java/libraries/io/src/processing/io/PWM.java
@@ -99,9 +99,6 @@ public void clear() {
 
   /**
    *  Gives ownership of a channel back to the operating system
-   *
-   *  Without calling this function the channel will remain in the current
-   *  state even after the sketch has been closed.
    *  @webref
    */
   public void close() {
@@ -187,10 +184,6 @@ public void set(int period, float duty) {
 
   /**
    *  Enables the PWM output with a preset period of 1 kHz
-   *
-   *  This period approximately matches the dedicated PWM pins on
-   *  the Arduino Uno, which have a frequency of 980 Hz.
-   *  It is recommended to use set(period, duty) instead.
    *  @param duty duty cycle, 0.0 (always off) to 1.0 (always on)
    *  @webref
    */
diff --git a/java/libraries/io/src/processing/io/SPI.java b/java/libraries/io/src/processing/io/SPI.java
