From 898e95b9d4e792ff20ed60365765da3748812eef Mon Sep 17 00:00:00 2001
From: Jonas Fonseca <fonseca@diku.dk>
Date: Sun, 7 Oct 2007 09:12:59 +0200
Subject: [PATCH] Further documentation updates and improvements

---
 src/authentication/AbstractAuthenticator.java |  8 ++++----
 src/authentication/Authenticator.java         |  6 +++---
 src/authentication/Credential.java            | 16 ++++++++--------
 src/authentication/package.html               |  1 +
 src/moteaccess/AbstractMoteAccess.java        | 11 ++++++-----
 src/moteaccess/MoteAccess.java                |  4 ++--
 src/moteaccess/package.html                   |  1 +
 src/motedata/ColumnHeader.java                | 20 ++++++++++----------
 src/motedata/MoteData.java                    |  4 ++--
 src/motedata/SimpleTable.java                 | 10 +++++-----
 src/motedata/package.html                     |  1 +
 src/util/package.html                         |  1 +
 12 files changed, 44 insertions(+), 39 deletions(-)
 create mode 100644 src/authentication/package.html
 create mode 100644 src/moteaccess/package.html
 create mode 100644 src/motedata/package.html
 create mode 100644 src/util/package.html

diff --git a/src/authentication/AbstractAuthenticator.java b/src/authentication/AbstractAuthenticator.java
index 031510c..11406b0 100644
--- a/src/authentication/AbstractAuthenticator.java
+++ b/src/authentication/AbstractAuthenticator.java
@@ -2,7 +2,7 @@ package authentication;
 
 import util.SQLHelper;
 
-/** Generic base class for the session authentication webservice
+/** Generic base class for the session authentication webservice.
  *
  * This is an abstract class with the generic code for the session
  * authentication web service. To integrate authentication for a user
@@ -14,7 +14,7 @@ import util.SQLHelper;
  */
 public abstract class AbstractAuthenticator {
 
-	/** Get an empty array of credential fields
+	/** Get an empty array of credential fields.
 	 *
 	 * This function should be implemented to return an array of
 	 * empty credential fields applicable for the user account
@@ -26,7 +26,7 @@ public abstract class AbstractAuthenticator {
 	 */
 	abstract public Credential[] getEmptyCredentials() throws Exception;
 
-	/** Authenticate session using with given credentials
+	/** Authenticate session using with given credentials.
 	 *
 	 * Authenticate an already open session with set of credential
 	 * provided by the client.
@@ -56,7 +56,7 @@ public abstract class AbstractAuthenticator {
 		}
 	}
 
-	/** Check the credentials used for client authentication
+	/** Check the credentials used for client authentication.
 	 *
 	 * This method should be implemented to check the credentials
 	 * used for client authentication.
diff --git a/src/authentication/Authenticator.java b/src/authentication/Authenticator.java
index 8cfd874..5b9cd16 100644
--- a/src/authentication/Authenticator.java
+++ b/src/authentication/Authenticator.java
@@ -3,14 +3,14 @@ package authentication;
 import java.sql.ResultSet;
 import util.SQLHelper;
 
-/** Basic session authenticator
+/** Basic session authenticator.
  *
  * This class is supposed to be used together with the user model
  * supplied with the Re-Mote database scripts.
  */
 public class Authenticator extends AbstractAuthenticator {
 
-	/** Get an empty array of credential fields
+	/** Get an empty array of credential fields.
 	 *
 	 * @return Empty fields for project, user, and password.
 	 * @throws Exception
@@ -26,7 +26,7 @@ public class Authenticator extends AbstractAuthenticator {
 		return credentials;
 	}
 
-	/** Check if the client supplied project, user, and password are valid
+	/** Check if the client supplied project, user, and password are valid.
 	 *
 	 * @param session_id    ID of the session.
 	 * @param credentials   The credentials supplied by the client
diff --git a/src/authentication/Credential.java b/src/authentication/Credential.java
index 5656260..5f2fd7d 100644
--- a/src/authentication/Credential.java
+++ b/src/authentication/Credential.java
@@ -2,7 +2,7 @@ package authentication;
 
 import java.io.Serializable;
 
-/** Authentication credential field
+/** Authentication credential field.
  *
  * This class corresponds to one credential value that should be
  * exchanged between the client and server in order to authenticate the
@@ -15,7 +15,7 @@ public class Credential implements Serializable{
 	private String label, value;
 	private boolean hidden;
 
-	/** Create field with given label and hidden attribute
+	/** Create field with given label and hidden attribute.
 	 *
 	 * @param label		The field label.
 	 * @param hidden	Whether the field should be hidden.
@@ -28,7 +28,7 @@ public class Credential implements Serializable{
 		this.hidden = hidden;
 	}
 
-	/** Dummy constructor to silence compiler */
+	/** Dummy constructor to silence compiler. */
 	public Credential()
 	{
 		this(null, false);
@@ -43,7 +43,7 @@ public class Credential implements Serializable{
 		return hidden;
 	}
 
-	/** Change hidden attribute of a field value
+	/** Change hidden attribute of a field value.
 	 *
 	 * @param hidden	The new state of the hidden attribute.
 	 */
@@ -52,7 +52,7 @@ public class Credential implements Serializable{
 		this.hidden = hidden;
 	}
 
-	/** Get field label
+	/** Get field label.
 	 *
 	 * @return The field label.
 	 */
@@ -61,7 +61,7 @@ public class Credential implements Serializable{
 		return label;
 	}
 
-	/** Set field label
+	/** Set field label.
 	 *
 	 * @param label		The field label.
 	 */
@@ -70,7 +70,7 @@ public class Credential implements Serializable{
 		this.label = label;
 	}
 
-	/** Get field value
+	/** Get field value.
 	 *
 	 * @return The field value. 
 	 */
@@ -79,7 +79,7 @@ public class Credential implements Serializable{
 		return value;
 	}
 
-	/** Set field value
+	/** Set field value.
 	 *
 	 * @param value	The new field value.
 	 */
diff --git a/src/authentication/package.html b/src/authentication/package.html
new file mode 100644
index 0000000..98b5f8a
--- /dev/null
+++ b/src/authentication/package.html
@@ -0,0 +1 @@
+<body>Web Service for Client Authentication</body>
diff --git a/src/moteaccess/AbstractMoteAccess.java b/src/moteaccess/AbstractMoteAccess.java
index 3295d53..e631885 100644
--- a/src/moteaccess/AbstractMoteAccess.java
+++ b/src/moteaccess/AbstractMoteAccess.java
@@ -3,15 +3,16 @@ package moteaccess;
 import java.sql.ResultSet;
 import util.SQLHelper;
 
-/**
- * @author zept
+/** Generic base class for assigning mote usage privileges.
+ *
  * This is an abstract class with the generic code to assign mote usage privileges.
  * To integrate any custom reservation system, this class must be inherited and the
  * abstract methods implemented.
+ * @author zept
  */
 public abstract class AbstractMoteAccess {
 
-	/** Acquire mote control privileges using specific session
+	/** Acquire mote control privileges using specific session.
 	 *
 	 * @param mote_ids	IDs of mote to control.
 	 * @param session_id	ID of session that wants privileges.
@@ -29,7 +30,7 @@ public abstract class AbstractMoteAccess {
 		return results;
 	}
 
-	/** Acquire control privilege for one mote
+	/** Acquire control privilege for one mote.
 	 *
 	 * @param mote_id	ID of mote to control.
 	 * @param session_id	ID of session that wants control privilege.
@@ -72,7 +73,7 @@ public abstract class AbstractMoteAccess {
 		}
 	}
 
-	/** Check if session can reserve a given mote
+	/** Check if session can reserve a given mote.
 	 *
 	 * This method must be implemented to integrate a custom
 	 * reservation system.  It is also a point for integration
diff --git a/src/moteaccess/MoteAccess.java b/src/moteaccess/MoteAccess.java
index c7449a4..21067d5 100644
--- a/src/moteaccess/MoteAccess.java
+++ b/src/moteaccess/MoteAccess.java
@@ -1,9 +1,9 @@
 package moteaccess;
 
-/** Basic mote accessor for system with no reservation */
+/** Basic mote accessor for system with no reservation. */
 public class MoteAccess extends AbstractMoteAccess {
 
-	/** Check if mote has a reservation
+	/** Check if mote has a reservation.
 	 *
 	 * @param mote_id	ID of the mote to check for reservation.
 	 * @param session_id	ID of the client session.
diff --git a/src/moteaccess/package.html b/src/moteaccess/package.html
new file mode 100644
index 0000000..d6a2350
--- /dev/null
+++ b/src/moteaccess/package.html
@@ -0,0 +1 @@
+<body>Web Service for Acquiring Mote Access and Control Privilege</body>
diff --git a/src/motedata/ColumnHeader.java b/src/motedata/ColumnHeader.java
index fdaf14a..a4ac6f6 100644
--- a/src/motedata/ColumnHeader.java
+++ b/src/motedata/ColumnHeader.java
@@ -2,7 +2,7 @@ package motedata;
 
 import java.io.Serializable;
 
-/** Table column container
+/** Table column container.
  *
  * Stores information about a column in a SimpleTable.
  */
@@ -14,7 +14,7 @@ public class ColumnHeader implements Serializable
 	private boolean visible;
 	private String valueclass;
 
-	/** Create column header
+	/** Create column header.
 	 *
 	 * @param title		The column title.
 	 * @param name		The column name.
@@ -30,13 +30,13 @@ public class ColumnHeader implements Serializable
 		this.valueclass = valueclass;
 	}
 
-	/** Dummy constructor to silence compiler warnings */
+	/** Dummy constructor to silence compiler warnings. */
 	public ColumnHeader()
 	{
 		this(null, null, false, null);
 	}
 
-	/** Get column header title
+	/** Get column header title.
 	 *
 	 * @return The column title. */
 	public String getTitle()
@@ -44,7 +44,7 @@ public class ColumnHeader implements Serializable
 		return title;
 	}
 
-	/** Set column header title
+	/** Set column header title.
 	 *
 	 * @param title	The new column title.
 	 */
@@ -53,7 +53,7 @@ public class ColumnHeader implements Serializable
 		this.title = title;
 	}
 
-	/** Get column header name
+	/** Get column header name.
 	 *
 	 * @return The column name.
 	 */
@@ -62,7 +62,7 @@ public class ColumnHeader implements Serializable
 		return name;
 	}
 
-	/** Set column header name
+	/** Set column header name.
 	 *
 	 * @param name	The new column name.
 	 */
@@ -80,7 +80,7 @@ public class ColumnHeader implements Serializable
 		return visible;
 	}
 
-	/** Set column header visibility
+	/** Set column header visibility.
 	 *
 	 * @param visible The new column visibility.
 	 */
@@ -89,7 +89,7 @@ public class ColumnHeader implements Serializable
 		this.visible = visible;
 	}
 
-	/** Get value class of column header
+	/** Get value class of column header.
 	 *
 	 * @return The value class of the column.
 	 */
@@ -98,7 +98,7 @@ public class ColumnHeader implements Serializable
 		return valueclass;
 	}
 
-	/** Set the column header value class
+	/** Set the column header value class.
 	 *
 	 * @param valueclass The column's new value class.
 	 */
diff --git a/src/motedata/MoteData.java b/src/motedata/MoteData.java
index bd954a6..5706659 100644
--- a/src/motedata/MoteData.java
+++ b/src/motedata/MoteData.java
@@ -6,7 +6,7 @@ import util.SQLHelper;
 import motedata.ColumnHeader;
 import motedata.SimpleTable;
 
-/** Service class for getting mote data
+/** Service class for getting mote data.
  *
  * The mote data can be anything from availability information, mote
  * attributes such as MAC and TOS address, as well as site attributes
@@ -14,7 +14,7 @@ import motedata.SimpleTable;
  */
 public class MoteData {
 
-	/** Get status information about all motes connected to a session
+	/** Get status information about all motes connected to a session.
 	 *
 	 * Builds a query to extract all info about connected motes
 	 * including mote and site attributes into a single table.
diff --git a/src/motedata/SimpleTable.java b/src/motedata/SimpleTable.java
index e4cb318..4f0438d 100644
--- a/src/motedata/SimpleTable.java
+++ b/src/motedata/SimpleTable.java
@@ -2,7 +2,7 @@ package motedata;
 
 import java.io.Serializable;
 
-/** Simple data table
+/** Simple data table.
  *
  * A simple container for storing data from a database query so it can
  * be exchanged between the server and client.
@@ -13,7 +13,7 @@ public class SimpleTable implements Serializable {
 	private ColumnHeader[] columnHeaders;
 	private Object[][] data;
 
-	/** Create a table with initial given size
+	/** Create a table with initial given size.
 	 *
 	 * @param rowCount	The number of rows in the table.
 	 * @param colCount	The number of columns in the table.
@@ -24,13 +24,13 @@ public class SimpleTable implements Serializable {
 		data = new Object[rowCount][colCount];
 	}
 
-	/** Dummy constructor to silence compiler warnings */
+	/** Dummy constructor to silence compiler warnings. */
 	public SimpleTable()
 	{
 		this(0, 0);
 	}
 
-	/** Get table column headers
+	/** Get table column headers.
 	 *
 	 * @return The column header of the table.
 	 */
@@ -39,7 +39,7 @@ public class SimpleTable implements Serializable {
 		return columnHeaders;
 	}
 
-	/** Get table data
+	/** Get table data.
 	 *
 	 * @return The object matrix.
 	 */
diff --git a/src/motedata/package.html b/src/motedata/package.html
new file mode 100644
index 0000000..e35be7c
--- /dev/null
+++ b/src/motedata/package.html
@@ -0,0 +1 @@
+<body>Web Service for Getting Information on Controlled Motes</body>
diff --git a/src/util/package.html b/src/util/package.html
new file mode 100644
index 0000000..5e1efea
--- /dev/null
+++ b/src/util/package.html
@@ -0,0 +1 @@
+<body>Utilities and Helpers</body>
-- 
2.11.4.GIT