From adfaed5e1acb8292443c9c08f83c2ca4fcc2123f Mon Sep 17 00:00:00 2001
From: Casey Reas <reas@reas.com>
Date: Wed, 27 Jul 2011 16:04:21 +0000
Subject: [PATCH] Basic 2.0 Ref changes

---
 .../net/src/processing/net/Client.java        | 100 +++++--------
 .../net/src/processing/net/Server.java        |  42 ++----
 .../serial/src/processing/serial/Serial.java  | 137 ++++++++++++------
 .../video/src/processing/video/Capture.java   |  60 +++++---
 .../video/src/processing/video/Movie.java     | 100 ++++++++-----
 5 files changed, 251 insertions(+), 188 deletions(-)

diff --git a/java/libraries/net/src/processing/net/Client.java b/java/libraries/net/src/processing/net/Client.java
index c05d2f881..983bc0b90 100644
--- a/java/libraries/net/src/processing/net/Client.java
+++ b/java/libraries/net/src/processing/net/Client.java
@@ -31,12 +31,8 @@ import java.lang.reflect.*;
 import java.net.*;
 
 /**
- * A client connects to a server and sends data back and forth.
- * If anything goes wrong with the connection,
- * for example the host is not there or is listening on a different port,
- * an exception is thrown.
- * 
- * @webref
+ * @generate Client.xml 
+ * @webref net
  * @brief The client class is used to create client Objects which connect to a server to exchange data. 
  * @instanceName client any variable of type Client
  * @usage Application
@@ -126,17 +122,10 @@ public class Client implements Runnable {
 
 
   /**
-   * Disconnects from the server. Use to shut the connection when you're finished with the Client.
-   * =advanced
-   * Disconnect from the server and calls disconnectEvent(Client c)
-   * in the host PApplet.
-   * <P/>
-   * Use this to shut the connection if you're finished with it
-   * while your applet is still running. Otherwise, it will be
-   * automatically be shut down by the host PApplet
-   * (using dispose, which is identical)
-   * @webref
+   * @generate Client_stop.xml
+   * @webref client:client
    * @brief Disconnects from the server
+   * @usage application
    */
   public void stop() {
     dispose();
@@ -230,9 +219,10 @@ public class Client implements Runnable {
 
 
   /**
-   * Returns the IP address of the computer to which the Client is attached.
+   * @generate Client_ip.xml
+   * @webref client:client
+   * @usage application
    * @brief Returns the IP address of the machine as a String
-   * @webref
    */
   public String ip() {
     return socket.getInetAddress().getHostAddress();
@@ -240,8 +230,9 @@ public class Client implements Runnable {
 
 
   /**
-   * Returns the number of bytes available. When any client has bytes available from the server, it returns the number of bytes.
-   * @webref
+   * @generate Client_available.xml
+   * @webref client:client
+   * @usage application
    * @brief Returns the number of bytes in the buffer waiting to be read
    */
   public int available() {
@@ -250,9 +241,9 @@ public class Client implements Runnable {
 
 
   /**
-   * Empty the buffer, removes all the data stored there.
-   * 
-   * @webref
+   * @generate Client_clear.xml 
+   * @webref client:client
+   * @usage application
    * @brief Clears the buffer
    */
   public void clear() {
@@ -262,10 +253,9 @@ public class Client implements Runnable {
 
 
   /**
-   * Returns a number between 0 and 255 for the next byte that's waiting in the buffer.
-   * Returns -1 if there is no byte, although this should be avoided by first cheacking <b>available()</b> to see if any data is available.
-   * 
-   * @webref
+   * @generate Client_read.xml
+   * @webref client:client
+   * @usage application
    * @brief Returns a value from the buffer
    */
   public int read() {
@@ -283,10 +273,9 @@ public class Client implements Runnable {
 
 
   /**
-   * Returns the next byte in the buffer as a char.
-   * Returns -1, or 0xffff, if nothing is there.
-   * 
-   * @webref
+   * @generate Client_readChar.xml
+   * @webref client:client
+   * @usage application
    * @brief Returns the next byte in the buffer as a char
    */
   public char readChar() {
@@ -296,19 +285,15 @@ public class Client implements Runnable {
 
 
   /**
-   * Reads a group of bytes from the buffer.
-   * The version with no parameters returns a byte array of all data in the buffer.
-   * This is not efficient, but is easy to use.
-   * The version with the <b>byteBuffer</b> parameter is more memory and time efficient.
-   * It grabs the data in the buffer and puts it into the byte array passed in and returns an int value for the number of bytes read.
-   * If more bytes are available than can fit into the <b>byteBuffer</b>, only those that fit are read.
-   * =advanced
+   * @generate Client_readBytes.xml
+   * <h3>Advanced</h3>
    * Return a byte array of anything that's in the serial buffer.
    * Not particularly memory/speed efficient, because it creates
    * a byte array on each read, but it's easier to use than
    * readBytes(byte b[]) (see below).
    * 
-   * @webref
+   * @webref client:client
+   * @usage application
    * @brief Reads everything in the buffer
    */
   public byte[] readBytes() {
@@ -327,6 +312,7 @@ public class Client implements Runnable {
 
 
   /**
+   * <h3>Advanced</h3>
    * Grab whatever is in the serial buffer, and stuff it into a
    * byte buffer passed in by the user. This is more memory/time
    * efficient than readBytes() returning a byte[] array.
@@ -356,14 +342,9 @@ public class Client implements Runnable {
 
 
   /**
-   * Reads from the port into a buffer of bytes up to and including a particular character.
-   * If the character isn't in the buffer, 'null' is returned.
-   * The version with no <b>byteBuffer</b> parameter returns a byte array of all data up to and including the <b>interesting</b> byte.
-   * This is not efficient, but is easy to use. The version with the <b>byteBuffer</b> parameter is more memory and time efficient.
-   * It grabs the data in the buffer and puts it into the byte array passed in and returns an int value for the number of bytes read.
-   * If the byte buffer is not large enough, -1 is returned and an error is printed to the message area. If nothing is in the buffer, 0 is returned.
-   * 
-   * @webref
+   * @generate Client_readBytesUntil.xml 
+   * @webref client:client
+   * @usage application
    * @brief Reads from the buffer of bytes up to and including a particular character
    * @param interesting character designated to mark the end of the data
    */
@@ -396,6 +377,7 @@ public class Client implements Runnable {
 
 
   /**
+   * <h3>Advanced</h3>
    * Reads from the serial port into a buffer of bytes until a
    * particular character. If the character isn't in the serial
    * buffer, then 'null' is returned.
@@ -442,13 +424,9 @@ public class Client implements Runnable {
 
 
   /**
-   * Returns the all the data from the buffer as a String.
-   * This method assumes the incoming characters are ASCII.
-   * If you want to transfer Unicode data,
-   * first convert the String to a byte stream in the representation of your choice
-   * (i.e. UTF8 or two-byte Unicode data), and send it as a byte array.
-   * 
-   * @webref
+   * @generate Client_readString.xml 
+   * @webref client:client
+   * @usage application
    * @brief Returns the buffer as a String
    */
   public String readString() {
@@ -458,14 +436,15 @@ public class Client implements Runnable {
 
 
   /**
-   * Combination of <b>readBytesUntil()</b> and <b>readString()</b>. Returns <b>null</b> if it doesn't find what you're looking for.
-   * =advanced
+   * @generate Client_readStringUntil.xml
+   * <h3>Advanced</h3>
    * <p/>
    * If you want to move Unicode data, you can first convert the
    * String to a byte stream in the representation of your choice
    * (i.e. UTF8 or two-byte Unicode data), and send it as a byte array.
    * 
-   * @webref
+   * @webref client:client
+   * @usage application
    * @brief Returns the buffer as a String up to and including a particular character
    * @param interesting character designated to mark the end of the data
    */
@@ -477,9 +456,9 @@ public class Client implements Runnable {
 
 
   /**
-   * Writes data to a server specified when constructing the client.
-   * 
-   * @webref
+   * @generate Client_write.xml 
+   * @webref client:client
+   * @usage application
    * @brief  	Writes bytes, chars, ints, bytes[], Strings
    * @param data data to write
    */
@@ -515,6 +494,7 @@ public class Client implements Runnable {
 
 
   /**
+   * <h3>Advanced</h3>
    * Write a String to the output. Note that this doesn't account
    * for Unicode (two bytes per char), nor will it send UTF8
    * characters.. It assumes that you mean to send a byte buffer
diff --git a/java/libraries/net/src/processing/net/Server.java b/java/libraries/net/src/processing/net/Server.java
index 7a5165a98..4d885d458 100644
--- a/java/libraries/net/src/processing/net/Server.java
+++ b/java/libraries/net/src/processing/net/Server.java
@@ -31,15 +31,11 @@ import java.lang.reflect.*;
 import java.net.*;
 
 /**
- * A server sends and receives data to and from its associated clients (other programs connected to it).
- * When a server is started, it begins listening for connections on the port specified by the <b>port</b> parameter.
- * Computers have many ports for transferring data and some are commonly used so be sure to not select one of these.
- * For example, web servers usually use port 80 and POP mail uses port 110.
- * 
- * @webref
+ * @generate Server.xml 
+ * @webref net
+ * @usage application
  * @brief The server class is used to create server objects which send and receives data to and from its associated clients (other programs connected to it). 
  * @instanceName server  	any variable of type Server
- * @usage  	Application
  */
 public class Server implements Runnable {
 
@@ -95,8 +91,8 @@ public class Server implements Runnable {
 
 
   /**
-   * Disconnect a particular client.
-   * @webref
+   * @generate Server_disconnect.xml
+   * @webref server:server
    * @param client the client to disconnect
    */
   public void disconnect(Client client) {
@@ -144,8 +140,9 @@ public class Server implements Runnable {
   int lastAvailable = -1;
 
   /**
-   * Returns the next client in line with a new message
-   * @webref
+   * @generate Server_available.xml
+   * @webref server
+   * @usage application
    */
   public Client available() {
     synchronized (clients) {
@@ -166,13 +163,14 @@ public class Server implements Runnable {
 
 
   /**
-   * Disconnects all clients and stops the server
-   * =advanced
+   * @generate Server_stop.xml
+   * <h3>Advanced</h3>
    * <p/>
    * Use this to shut down the server if you finish using it while your applet 
    * is still running. Otherwise, it will be automatically be shut down by the 
    * host PApplet using dispose(), which is identical. 
-   * @webref
+   * @webref server
+   * @usage application
    */
   public void stop() {
     dispose();
@@ -236,10 +234,8 @@ public class Server implements Runnable {
 
 
   /**
-   * Write a value to all the connected clients.
-   * See Client.write() for operational details.
-   * 
-   * @webref
+   * @generate Server_write.xml 
+   * @webref server
    * @brief Writes data to all connected clients
    * @param data data to write
    */
@@ -255,11 +251,6 @@ public class Server implements Runnable {
     }
   }
 
-
-  /**
-   * Write a byte array to all the connected clients.
-   * See Client.write() for operational details.
-   */
   public void write(byte data[]) {
     int index = 0;
     while (index < clientCount) {
@@ -272,11 +263,6 @@ public class Server implements Runnable {
     }
   }
 
-
-  /**
-   * Write a String to all the connected clients.
-   * See Client.write() for operational details.
-   */
   public void write(String data) {
     int index = 0;
     while (index < clientCount) {
diff --git a/java/libraries/serial/src/processing/serial/Serial.java b/java/libraries/serial/src/processing/serial/Serial.java
index 35f590b15..a6197592a 100644
--- a/java/libraries/serial/src/processing/serial/Serial.java
+++ b/java/libraries/serial/src/processing/serial/Serial.java
@@ -32,8 +32,9 @@ import java.util.*;
 import java.lang.reflect.*;
 
 /**
- * Class for sending and receiving data using the serial communication protocol.
- * @webref
+ * @generate Serial.xml
+ * @webref net
+ * @usage application
  */
 public class Serial implements SerialPortEventListener {
 
@@ -92,15 +93,23 @@ public class Serial implements SerialPortEventListener {
       new Float(props.getProperty("serial.stopbits", "1")).floatValue();
   }
 
-
+/**
+ * @param parent typically use "this"
+ */
   public Serial(PApplet parent) {
     this(parent, dname, drate, dparity, ddatabits, dstopbits);
   }
-
+  
+/**
+ * @param irate 9600 is the default
+ */
   public Serial(PApplet parent, int irate) {
     this(parent, dname, irate, dparity, ddatabits, dstopbits);
   }
 
+/**
+ * @param iname name of the port (COM1 is the default)
+ */
   public Serial(PApplet parent, String iname, int irate) {
     this(parent, iname, irate, dparity, ddatabits, dstopbits);
   }
@@ -109,6 +118,11 @@ public class Serial implements SerialPortEventListener {
     this(parent, iname, drate, dparity, ddatabits, dstopbits);
   }
 
+/**
+ * @param iparity 'N' for none, 'E' for even, 'O' for odd ('N' is the default)
+ * @param idatabits 8 is the default
+ * @param istopbits 1.0, 1.5, or 2.0 (1.0 is the default)
+ */
   public Serial(PApplet parent, String iname, int irate,
                  char iparity, int idatabits, float istopbits) {
     //if (port != null) port.close();
@@ -172,13 +186,9 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
-   * Stop talking to serial and shut things down.
-   * <P>
-   * Basically just a user-accessible version of dispose().
-   * For now, it just calls dispose(), but dispose shouldn't
-   * be called from applets, because in some libraries,
-   * dispose() blows shit up if it's called by a user who
-   * doesn't know what they're doing.
+   * @generate Serial_stop.xml
+   * @webref serial:serial
+   * @usage web_application
    */
   public void stop() {
     dispose();
@@ -217,7 +227,12 @@ public class Serial implements SerialPortEventListener {
         port.setDTR(state);
   }
 
-
+/**
+ * @generate serialEvent.xml
+ * @webref serial:events
+ * @usage web_application
+ * @param serialEvent the port where new data is available
+ */
   synchronized public void serialEvent(SerialPortEvent serialEvent) {
     if (serialEvent.getEventType() == SerialPortEvent.DATA_AVAILABLE) {
       try {
@@ -255,8 +270,10 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
-   * Set number of bytes to buffer before calling serialEvent()
-   * in the host applet.
+   * @generate Serial_buffer.xml
+   * @webref serial:serial
+   * @usage web_application
+   * @param count number of bytes to buffer
    */
   public void buffer(int count) {
     bufferUntil = false;
@@ -265,8 +282,10 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
-   * Set a specific byte to buffer until before calling
-   * serialEvent() in the host applet.
+   * @generate Serial_bufferUntil.xml
+   * @webref serial:serial
+   * @usage web_application
+   * @param what the value to buffer until
    */
   public void bufferUntil(int what) {
     bufferUntil = true;
@@ -275,8 +294,9 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
-   * Returns the number of bytes that have been read from serial
-   * and are waiting to be dealt with by the user.
+   * @generate Serial_available.xml
+   * @webref serial:serial
+   * @usage web_application
    */
   public int available() {
     return (bufferLast - bufferIndex);
@@ -284,7 +304,9 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
-   * Ignore all the bytes read so far and empty the buffer.
+   * @generate Serial_clear.xml
+   * @webref serial:serial
+   * @usage web_application
    */
   public void clear() {
     bufferLast = 0;
@@ -293,10 +315,9 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
-   * Returns a number between 0 and 255 for the next byte that's
-   * waiting in the buffer.
-   * Returns -1 if there was no byte (although the user should
-   * first check available() to see if things are ready to avoid this)
+   * @generate Serial_read.xml
+   * @webref serial:serial
+   * @usage web_application
    */
   public int read() {
     if (bufferIndex == bufferLast) return -1;
@@ -313,9 +334,13 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
+   * @generate Serial_last.xml
+   * <h3>Advanced</h3>
    * Same as read() but returns the very last value received
    * and clears the buffer. Useful when you just want the most
    * recent value sent over the port.
+   * @webref serial:serial
+   * @usage web_application
    */
   public int last() {
     if (bufferIndex == bufferLast) return -1;
@@ -329,8 +354,9 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
-   * Returns the next byte in the buffer as a char.
-   * Returns -1, or 0xffff, if nothing is there.
+   * @generate Serial_readChar.xml
+   * @webref serial:serial
+   * @usage web_application
    */
   public char readChar() {
     if (bufferIndex == bufferLast) return (char)(-1);
@@ -339,7 +365,9 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
-   * Just like last() and readChar().
+   * @generate Serial_lastChar.xml
+   * @webref serial:serial
+   * @usage web_application
    */
   public char lastChar() {
     if (bufferIndex == bufferLast) return (char)(-1);
@@ -348,10 +376,9 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
-   * Return a byte array of anything that's in the serial buffer.
-   * Not particularly memory/speed efficient, because it creates
-   * a byte array on each read, but it's easier to use than
-   * readBytes(byte b[]) (see below).
+   * @generate Serial_readBytes.xml 
+   * @webref serial:serial
+   * @usage web_application
    */
   public byte[] readBytes() {
     if (bufferIndex == bufferLast) return null;
@@ -369,6 +396,7 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
+   * <h3>Advanced</h3>
    * Grab whatever is in the serial buffer, and stuff it into a
    * byte buffer passed in by the user. This is more memory/time
    * efficient than readBytes() returning a byte[] array.
@@ -396,9 +424,10 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
-   * Reads from the serial port into a buffer of bytes up to and
-   * including a particular character. If the character isn't in
-   * the serial buffer, then 'null' is returned.
+   * @generate Serial_readBytesUntil.xml
+   * @webref serial:serial
+   * @usage web_application
+   * @param interesting character designated to mark the end of the data
    */
   public byte[] readBytesUntil(int interesting) {
     if (bufferIndex == bufferLast) return null;
@@ -429,14 +458,12 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
-   * Reads from the serial port into a buffer of bytes until a
-   * particular character. If the character isn't in the serial
-   * buffer, then 'null' is returned.
-   *
+   * <h3>Advanced</h3>
    * If outgoing[] is not big enough, then -1 is returned,
    *   and an error message is printed on the console.
    * If nothing is in the buffer, zero is returned.
    * If 'interesting' byte is not in the buffer, then 0 is returned.
+   * @param outgoing passed in byte array to be altered
    */
   public int readBytesUntil(int interesting, byte outgoing[]) {
     if (bufferIndex == bufferLast) return 0;
@@ -473,12 +500,9 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
-   * Return whatever has been read from the serial port so far
-   * as a String. It assumes that the incoming characters are ASCII.
-   *
-   * If you want to move Unicode data, you can first convert the
-   * String to a byte stream in the representation of your choice
-   * (i.e. UTF8 or two-byte Unicode data), and send it as a byte array.
+   * @generate Serial_readString.xml
+   * @webref serial:serial
+   * @usage web_application
    */
   public String readString() {
     if (bufferIndex == bufferLast) return null;
@@ -487,13 +511,15 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
-   * Combination of readBytesUntil and readString. See caveats in
-   * each function. Returns null if it still hasn't found what
-   * you're looking for.
-   *
+   * @generate Serial_readStringUntil.xml
+   *<h3>Advanced</h3>
    * If you want to move Unicode data, you can first convert the
    * String to a byte stream in the representation of your choice
    * (i.e. UTF8 or two-byte Unicode data), and send it as a byte array.
+   *
+   * @webref serial:serial
+   * @usage web_application
+   * @param interesting character designated to mark the end of the data
    */
   public String readStringUntil(int interesting) {
     byte b[] = readBytesUntil(interesting);
@@ -503,7 +529,9 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
+   * <h3>Advanced</h3>
    * This will handle both ints, bytes and chars transparently.
+   * @param what data to write
    */
   public void write(int what) {  // will also cover char
     try {
@@ -515,7 +543,9 @@ public class Serial implements SerialPortEventListener {
     }
   }
 
-
+ /**
+  * @param bytes[] data to write
+  */
   public void write(byte bytes[]) {
     try {
       output.write(bytes);
@@ -529,6 +559,8 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
+   * @generate Serial_write.xml
+   * <h3>Advanced</h3>
    * Write a String to the output. Note that this doesn't account
    * for Unicode (two bytes per char), nor will it send UTF8
    * characters.. It assumes that you mean to send a byte buffer
@@ -539,6 +571,10 @@ public class Serial implements SerialPortEventListener {
    * If you want to move Unicode data, you can first convert the
    * String to a byte stream in the representation of your choice
    * (i.e. UTF8 or two-byte Unicode data), and send it as a byte array.
+   *
+   * @webref serial:serial
+   * @usage web_application
+   * @param what data to write
    */
   public void write(String what) {
     write(what.getBytes());
@@ -546,9 +582,14 @@ public class Serial implements SerialPortEventListener {
 
 
   /**
+   * @generate Serial_list.xml
+   * <h3>Advanced</h3>
    * If this just hangs and never completes on Windows,
    * it may be because the DLL doesn't have its exec bit set.
    * Why the hell that'd be the case, who knows.
+   * 
+   * @webref serial
+   * @usage web_application
    */
   static public String[] list() {
     Vector<String> list = new Vector<String>();
diff --git a/java/libraries/video/src/processing/video/Capture.java b/java/libraries/video/src/processing/video/Capture.java
index 6c497a0e4..f7ae595e7 100644
--- a/java/libraries/video/src/processing/video/Capture.java
+++ b/java/libraries/video/src/processing/video/Capture.java
@@ -72,9 +72,16 @@ public class Capture extends PImage implements PConstants {
   protected int reqWidth;
   protected int reqHeight;  
   
-  /**
+  /**
+   * @generate Capture.xml
+   * <h3>Advanced</h3>
    * Basic constructor: tries to auto-detect all the capture parameters,
-   * with the exception of the resolution.
+   * with the exception of the resolution.
+   * @webref video
+   * @usage application
+   * @param parent typically use "this"
+   * @param requestWidth width of the frame
+   * @param requestHeight height of the frame
    */
   public Capture(PApplet parent, int requestWidth, int requestHeight) {
     super(requestWidth, requestHeight, RGB);
@@ -83,7 +90,9 @@ public class Capture extends PImage implements PConstants {
   }
 
   /**
-   * Constructor that takes resolution and framerate indicated as a single number.
+   * <h3>Advanced</h3>
+   * Constructor that takes resolution and framerate indicated as a single number.
+   * @param frameRate number of frames to read per second
    */  
   public Capture(PApplet parent, int requestWidth, int requestHeight, int frameRate) {
     super(requestWidth, requestHeight, RGB);
@@ -92,8 +101,10 @@ public class Capture extends PImage implements PConstants {
   }
 
   /**
+   * <h3>Advanced</h3>
    * This constructor allows to specify the camera name. In Linux, for example, this
-   * should be a string of the form /dev/video0, /dev/video1, etc.
+   * should be a string of the form /dev/video0, /dev/video1, etc.
+   * @param cameraName name of the camera
    */   
   public Capture(PApplet parent, int requestWidth, int requestHeight, String cameraName) {
     super(requestWidth, requestHeight, RGB);
@@ -102,6 +113,7 @@ public class Capture extends PImage implements PConstants {
   }
 
   /**
+   * <h3>Advanced</h3>
    * This constructor allows to specify the camera name and the desired framerate.
    */     
   public Capture(PApplet parent, int requestWidth, int requestHeight, int frameRate, 
@@ -113,8 +125,10 @@ public class Capture extends PImage implements PConstants {
   }  
   
   /**
+   * <h3>Advanced</h3>
    * This constructor lets to indicate which source element to use (i.e.: v4l2src, 
-   * osxvideosrc, dshowvideosrc, ksvideosrc, etc).
+   * osxvideosrc, dshowvideosrc, ksvideosrc, etc).
+   * @param sourceName ???
    */   
   public Capture(PApplet parent, int requestWidth, int requestHeight, int frameRate, 
                    String sourceName, String cameraName) {
@@ -125,9 +139,12 @@ public class Capture extends PImage implements PConstants {
   }
 
   /**
+   * <h3>Advanced</h3>
    * This constructor accepts an arbitrary list of string properties for the source element.
    * The camera name could be one of these properties. The framerate must be specified
-   * as a fraction string: 30/1, 15/2, etc.
+   * as a fraction string: 30/1, 15/2, etc.
+   * @param strPropNames ???
+   * @param strPropValues ???
    */    
   public Capture(PApplet parent, int requestWidth, int requestHeight, String frameRate,
                    String sourceName, String[] strPropNames, String[] strPropValues) {
@@ -137,9 +154,12 @@ public class Capture extends PImage implements PConstants {
   }
 
   /**
+   * <h3>Advanced</h3>
    * This constructor accepts an arbitrary list of string properties for the source element,
    * as well as a list of integer properties. This could be useful if a camera cannot by
-   * specified by name but by index. Framerate must be a fraction string: 30/1, 15/2, etc.
+   * specified by name but by index. Framerate must be a fraction string: 30/1, 15/2, etc.
+   * @param intPropNames ???
+   * @param intPropValues ???
    */   
   public Capture(PApplet parent, int requestWidth, int requestHeight, String frameRate,
                    String sourceName, String[] strPropNames, String[] strPropValues,
@@ -247,9 +267,9 @@ public class Capture extends PImage implements PConstants {
   }
   
   /**
-   * Returns "true" when a new video frame is available to read.
-   * 
-   * @return boolean
+   * @generate Capture_available.xml
+   * @webref capture
+   * @usage web_application
    */
   public boolean available() {
     return available;
@@ -286,7 +306,9 @@ public class Capture extends PImage implements PConstants {
   }
 
   /**
-   * Stops the capture pipeline.
+   * @generate Capture_stop.xml
+   * @webref capture
+   * @usage web_application
    */
   public void stop() {
     capturing = false;
@@ -294,11 +316,13 @@ public class Capture extends PImage implements PConstants {
   }  
   
   /**
-   * Reads the current video frame.
-   * 
+   * @generate Capture_read.xml
+   * <h3>Advanced</h3>
    * This method() and invokeEvent() are now synchronized, so that invokeEvent()
    * can't be called whilst we're busy reading. Problematic frame error
-   * fixed by Charl P. Botha <charlbotha.com>
+   * fixed by Charl P. Botha <charlbotha.com>
+   * @webref capture
+   * @usage web_application
    */
   public synchronized void read() {
     // We loadPixels() first to ensure that at least we always have a non-null
@@ -378,9 +402,9 @@ public class Capture extends PImage implements PConstants {
   }  
   
   /**
-   * Returns a list of available capture devices.
-   * 
-   * @return String[]
+   * @generate Capture_list.xml
+   * @webref capture
+   * @usage web_application
    */  
   static public String[] list() {
     if (PApplet.platform == LINUX) {
@@ -395,11 +419,11 @@ public class Capture extends PImage implements PConstants {
   }
 
   /**
+   * <h3>Advanced</h3>
    * Get a list of all available captures as a String array. i.e.
    * println(Capture.list()) will show you the goodies.
    * 
    * @param sourceName String
-   * @return String[]
    */
   static public String[] list(String sourceName) {
     return list(sourceName, devicePropertyName());
diff --git a/java/libraries/video/src/processing/video/Movie.java b/java/libraries/video/src/processing/video/Movie.java
index b9a568e20..13cac0a1e 100644
--- a/java/libraries/video/src/processing/video/Movie.java
+++ b/java/libraries/video/src/processing/video/Movie.java
@@ -32,9 +32,10 @@ import org.gstreamer.*;
 import org.gstreamer.Buffer;
 import org.gstreamer.elements.*;
 
-/**
- * This class makes it possible to load movies and to play them back in many
- * ways including looping, pausing, and changing speed.
+/**
+ * @generate Movie.xml
+ * @webref video
+ * @usage application
  */
 public class Movie extends PImage implements PConstants {
   protected String filename;
@@ -209,11 +210,10 @@ public class Movie extends PImage implements PConstants {
   }  
   
   /**
-   * Set how often new frames are to be read from the movie. Does not actually
-   * set the speed of the movie playback, that's handled by the speed() method.
-   * 
-   * @param float ifps
-   * @see speed
+   * @generate Movie_frameRate.xml
+   * @webref movie
+   * @usage web_application 
+   * @param ifps speed of the movie in frames per second
    */
   public void frameRate(float ifps) {
     // We calculate the target ratio in the case both the 
@@ -252,11 +252,12 @@ public class Movie extends PImage implements PConstants {
   }
 
   /**
-   * Set a multiplier for how fast/slow the movie should be run. The default is
-   * 1.0. speed(2) will play the movie at double speed (2x). speed(0.5) will
-   * play at half speed. speed(-1) will play backwards at regular speed.
-   * 
-   * @param float irate
+   * @generate Movie_speed.xml
+   
+   * @webref movie
+   
+   * @usage web_application 
+   * @param irate speed multiplier for movie playback
    */
   public void speed(float irate) {
     // If the frameRate() method is called continuously with very similar
@@ -269,9 +270,11 @@ public class Movie extends PImage implements PConstants {
   }
   
   /**
-   * Get the full length of this movie (in seconds).
-   * 
-   * @return float
+   * @generate Movie_duration.xml
+   
+   * @webref movie
+   
+   * @usage web_application
    */
   public float duration() {
     float sec = gplayer.queryDuration().toSeconds();
@@ -280,9 +283,11 @@ public class Movie extends PImage implements PConstants {
   }  
   
   /**
-   * Return the current time in seconds.
-   * 
-   * @return float
+   * @generate Movie_time.xml
+   
+   * @webref movie
+   
+   * @usage web_application 
    */
   public float time() {
     float sec = gplayer.queryPosition().toSeconds();
@@ -309,10 +314,12 @@ public class Movie extends PImage implements PConstants {
   }
 
   /**
-   * Jump to a specific location (in seconds). The number is a float so
-   * fractions of seconds can be used.
-   * 
-   * @param float where
+   * @generate Movie_jump.xml
+   
+   * @webref movie
+   
+   * @usage web_application 
+   * @param where position to jump to specified in seconds
    */
   public void jump(float where) {
     if (playing) {
@@ -338,7 +345,7 @@ public class Movie extends PImage implements PConstants {
   /**
    * Jump to a specific frame.
    * 
-   * @param frame int
+   * @param frame ???
    */  
   public void jump(int frame) {
     float srcFramerate = getSourceFrameRate();
@@ -368,10 +375,11 @@ public class Movie extends PImage implements PConstants {
   }
   
   /**
-   * Return the true or false depending on whether there is a new frame ready to
-   * be read.
-   * 
-   * @return boolean
+   * @generate Movie_available.xml
+   
+   * @webref movie
+   
+   * @usage web_application 
    */
   public boolean available() {
     return available;
@@ -406,7 +414,11 @@ public class Movie extends PImage implements PConstants {
   }
   
   /**
-   * Begin playing the movie, with no repeat.
+   * @generate Movie_play.xml
+   
+   * @webref movie
+   
+   * @usage web_application
    */
   public void play() {
     if (!sinkReady) {
@@ -419,7 +431,11 @@ public class Movie extends PImage implements PConstants {
   }
 
   /**
-   * Begin playing the movie, with repeat.
+   * @generate Movie_loop.xml
+   
+   * @webref movie
+   
+   * @usage web_application
    */
   public void loop() {    
     repeat = true;
@@ -427,14 +443,22 @@ public class Movie extends PImage implements PConstants {
   }
 
   /**
-   * Shut off the repeating loop.
+   * @generate Movie_noLoop.xml
+   
+   * @webref movie
+   
+   * @usage web_application
    */
   public void noLoop() {
     repeat = false;
   }
 
   /**
-   * Pause the movie at its current time.
+   * @generate Movie_pause.xml
+   
+   * @webref movie
+   
+   * @usage web_application
    */
   public void pause() {
     playing = false;
@@ -443,7 +467,11 @@ public class Movie extends PImage implements PConstants {
   }
 
   /**
-   * Stop the movie, and rewind.
+   * @generate Movie_stop.xml
+   
+   * @webref movie
+   
+   * @usage web_application
    */
   public void stop() {
     if (playing) {      
@@ -455,7 +483,11 @@ public class Movie extends PImage implements PConstants {
   }
 
   /**
-   * Reads the current video frame.
+   * @generate Movie_read.xml
+   
+   * @webref movie
+   
+   * @usage web_application
    */
   public synchronized void read() {
     if (fps <= 0) {