From ec11eeeb5288f7d1048aed90874cd896468159d4 Mon Sep 17 00:00:00 2001
From: Jakub Skoczen <jakub@indexdata.dk>
Date: Tue, 12 Feb 2013 17:05:25 +0100
Subject: [PATCH] Java docs

---
 src/main/java/org/yaz4j/Connection.java         |    2 +-
 src/main/java/org/yaz4j/ConnectionExtended.java |   14 ++++++++++++++
 src/main/java/org/yaz4j/Package.java            |   10 ++++++++++
 src/main/java/org/yaz4j/ResultSet.java          |   16 ++++++++++++----
 4 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/src/main/java/org/yaz4j/Connection.java b/src/main/java/org/yaz4j/Connection.java
index 4d3f240..49d5aea 100644
--- a/src/main/java/org/yaz4j/Connection.java
+++ b/src/main/java/org/yaz4j/Connection.java
@@ -14,7 +14,7 @@ import org.yaz4j.jni.yaz4jlib;
  * a socket) to the remote server as the programmer may want to specify options
  * on the object before establishing the actual connection.
  *
- * The worflow for synchronous (the only addressed) operation when using this
+ * The work-flow for synchronous (the only addressed) operation when using this
  * class should be as follows (in pseudocode):
  *
  * <blockquote><pre>
diff --git a/src/main/java/org/yaz4j/ConnectionExtended.java b/src/main/java/org/yaz4j/ConnectionExtended.java
index f9ac03e..12e3085 100644
--- a/src/main/java/org/yaz4j/ConnectionExtended.java
+++ b/src/main/java/org/yaz4j/ConnectionExtended.java
@@ -4,12 +4,26 @@ import org.yaz4j.jni.SWIGTYPE_p_ZOOM_options_p;
 import org.yaz4j.jni.SWIGTYPE_p_ZOOM_package_p;
 import org.yaz4j.jni.yaz4jlib;
 
+/**
+ * Offers an interface to a subset of the Z39.50 extended services as well as a 
+ * few privately defined ones. E.g, Z59.50 ILL, record update, database drop,
+ * create, commit.
+ * 
+ * @see <a href="http://www.indexdata.com/yaz/doc/zoom.extendedservices.html">ZOOM Extended Services</a>
+ * 
+ * @author jakub
+ */
 public class ConnectionExtended extends Connection {
 
   public ConnectionExtended(String host, int port) {
     super(host, port);
   }
 
+  /**
+   * Creates an extended-services package for the connection.
+   * @param type type of package (operation)
+   * @return 
+   */
   public Package getPackage(String type) {
     if (closed) {
       throw new IllegalStateException("Connection is closed.");
diff --git a/src/main/java/org/yaz4j/Package.java b/src/main/java/org/yaz4j/Package.java
index 15635eb..83aa74b 100644
--- a/src/main/java/org/yaz4j/Package.java
+++ b/src/main/java/org/yaz4j/Package.java
@@ -3,6 +3,16 @@ package org.yaz4j;
 import org.yaz4j.jni.SWIGTYPE_p_ZOOM_package_p;
 import org.yaz4j.jni.yaz4jlib;
 
+/**
+ * Allows to perform an extended-service operation.
+ * 
+ * Once created, a package is configured by means of options, then the package 
+ * is send and the result is inspected (again, by means of options).
+ * 
+ * @see org.yaz4j.ConnectionExtended#getPackage(java.lang.String) 
+ * 
+ * @author jakub
+ */
 public class Package {
 
   private SWIGTYPE_p_ZOOM_package_p pack;
diff --git a/src/main/java/org/yaz4j/ResultSet.java b/src/main/java/org/yaz4j/ResultSet.java
index e2df507..2dc3e50 100644
--- a/src/main/java/org/yaz4j/ResultSet.java
+++ b/src/main/java/org/yaz4j/ResultSet.java
@@ -12,20 +12,20 @@ import org.yaz4j.jni.yaz4jlib;
 
 /**
  * This class represents a "buffered handle" to the result set created on the
- * server and thus retrieving records may invlove a request to the server if
+ * server and thus retrieving records may involve a request to the server if
  * those records are not locally cached. Details on how to configure the retrieval
  * (present) process are available in the YAZ manual
  *
  * @see <a href="http://www.indexdata.com/yaz/doc/zoom.resultsets.html">YAZ ZOOM result sets</a>
  *
- * Becacuse of the server misbehaviour or errors during retrieval the
+ * Because of server misbehavior or errors during retrieval the
  * "getRecord" method may either return null or throw exceptions, even when the
  * index of retrieved records lies within the bounds of the set. Client
  * code should be prepared for such situations.
  *
  * This class implements the iterable interface and as such can be used within
- * foreach loops, it's important to note however that in this case the errors
- * during retrieval will be masked with standard NoSuchElementExceptions
+ * foreach loops, it's important to note, however, that in this case the errors
+ * during retrieval will be masked with standard NoSuchElementExceptions.
  *
  * @author jakub
  */
@@ -82,6 +82,14 @@ public class ResultSet implements Iterable<Record> {
     return new Record(record, this);
   }
   
+  /**
+   * Retrieve a collection of records at once. If a record cannot be retrieved,
+   * it is omitted from the list (thus the list size may be smaller than 'count').
+   * @param start start index within the result set
+   * @param count number of records to retrieve
+   * @return
+   * @throws ZoomException raised in case of protocol errors
+   */
   public List<Record> getRecords(long start, int count) throws ZoomException {
     List<Record> out = new ArrayList<Record>(count);
     SWIGTYPE_p_p_ZOOM_record_p recs = yaz4jlib.new_zoomRecordArray(count);
-- 
1.7.10.4