Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUAbstractRequest.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUAbstractRequest.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUAbstractRequest.java	(revision 2088)
@@ -1,2 +1,18 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
@@ -6,41 +22,43 @@
 
 
-public abstract class SRUAbstractRequest {
-    protected static final String PARAM_OPERATION         = "operation";
-    protected static final String PARAM_VERSION           = "version";
-    protected static final String PARAM_RECORD_PACKING    = "recordPacking";
-    protected static final String PARAM_STYLESHEET        = "stylesheet";
-    protected static final String PARAM_QUERY             = "query";
-    protected static final String PARAM_START_RECORD      = "startRecord";
-    protected static final String PARAM_MAXIMUM_RECORDS   = "maximumRecords";
-    protected static final String PARAM_RECORD_SCHEMA     = "recordSchema";
-    protected static final String PARAM_RECORD_X_PATH     = "recordXPath";
-    protected static final String PARAM_RESULT_SET_TTL    = "resultSetTTL";
-    protected static final String PARAM_SORT_KEYS         = "sortKeys";
-    protected static final String PARAM_SCAN_CLAUSE       = "scanClause";
-    protected static final String PARAM_RESPONSE_POSITION = "responsePosition";
-    protected static final String PARAM_MAXIMUM_TERMS     = "maximumTerms";
-    protected static final String RECORD_PACKING_XML      = "xml";
-    protected static final String RECORD_PACKING_STRING   = "string";
-    private static final String OP_EXPLAIN                = "explain";
-    private static final String OP_SCAN                   = "scan";
-    private static final String OP_SEARCH_RETRIEVE        = "searchRetrieve";
-    private static final String VERSION_1_1               = "1.1";
-    private static final String VERSION_1_2               = "1.2";
-    private static final String PARAM_EXTENSION_PREFIX    = "x-";
-    /** for end-point conformance testing only. never use in production */
-    public static final String X_MALFORMED_VERSION       =
+abstract class SRUAbstractRequest {
+    static final String PARAM_OPERATION                = "operation";
+    static final String PARAM_VERSION                  = "version";
+    static final String PARAM_RECORD_PACKING           = "recordPacking";
+    static final String PARAM_STYLESHEET               = "stylesheet";
+    static final String PARAM_QUERY                    = "query";
+    static final String PARAM_START_RECORD             = "startRecord";
+    static final String PARAM_MAXIMUM_RECORDS          = "maximumRecords";
+    static final String PARAM_RECORD_SCHEMA            = "recordSchema";
+    static final String PARAM_RECORD_X_PATH            = "recordXPath";
+    static final String PARAM_RESULT_SET_TTL           = "resultSetTTL";
+    static final String PARAM_SORT_KEYS                = "sortKeys";
+    static final String PARAM_SCAN_CLAUSE              = "scanClause";
+    static final String PARAM_RESPONSE_POSITION        = "responsePosition";
+    static final String PARAM_MAXIMUM_TERMS            = "maximumTerms";
+    static final String RECORD_PACKING_XML             = "xml";
+    static final String RECORD_PACKING_STRING          = "string";
+    private static final String OP_EXPLAIN             = "explain";
+    private static final String OP_SCAN                = "scan";
+    private static final String OP_SEARCH_RETRIEVE     = "searchRetrieve";
+    private static final String VERSION_1_1            = "1.1";
+    private static final String VERSION_1_2            = "1.2";
+    private static final String PARAM_EXTENSION_PREFIX = "x-";
+    /** for end-point conformance testing only. never use in production. */
+    public static final String X_MALFORMED_VERSION     =
             "x-malformed-version";
-    /** for end-point conformance testing only. never use in production */
-    public static final String X_MALFORMED_OPERATION     =
+    /** for end-point conformance testing only. never use in production. */
+    public static final String X_MALFORMED_OPERATION   =
             "x-maformed-operation";
-    /** for end-point conformance testing only. never use in production */
-    public static final String MALFORMED_OMIT            = "omit";
-
-    protected enum SRUOperation {
+    /** for end-point conformance testing only. never use in production. */
+    public static final String MALFORMED_OMIT          = "omit";
+
+
+    enum SRUOperation {
         EXPLAIN, SCAN, SEARCH_RETRIEVE
     } // enum SRUOperation
 
-    protected class URIBuilder {
+    
+    class URIBuilder {
         private final StringBuilder sb;
         private boolean firstParam = true;
@@ -50,5 +68,5 @@
         }
 
-
+        
         public URIBuilder append(String name, String value) {
             if (name == null) {
@@ -75,5 +93,5 @@
         }
 
-
+        
         public URIBuilder append(String name, int value) {
             return append(name, Integer.toString(value));
@@ -85,6 +103,9 @@
         }
     } // class
+    /** The URL of the endpoint. */
     protected final String endpointURI;
+    /** The version to be sued  for this request. */
     protected SRUVersion version;
+    /** A map of extra request data parameters. */
     protected Map<String, String> extraRequestData;
     private SRUVersion versionPreformed;
@@ -99,4 +120,9 @@
 
 
+    /**
+     * Get the endpoint URI.
+     * 
+     * @return the endpoiunt URI
+     */
     public String getEndpointURI() {
         return endpointURI;
@@ -104,4 +130,9 @@
 
 
+    /**
+     * Set the version for this request.
+     * 
+     * @param version a version of <code>null</code> for client default
+     */
     public void setVersion(SRUVersion version) {
         this.version = version;
@@ -109,4 +140,10 @@
 
 
+    /**
+     * Get the version for this request.
+     * 
+     * @return version for this request or <code>null</code> of client default
+     *         is used
+     */
     public SRUVersion getVersion() {
         return version;
@@ -114,9 +151,18 @@
 
 
-    public SRUVersion getVersionPerformed() {
-        return versionPreformed;
-    }
-
-
+    /**
+     * Set an extra request parameter for this request.
+     * 
+     * @param name
+     *            the name for the extra request data parameter
+     * @param value
+     *            the value for the extra request data parameter
+     * @throws NullPointerException
+     *             if any required argument is <code>null</code>
+     * @throws IllegalArgumentException
+     *             if any argument is invalid
+     * @see <a href="http://www.loc.gov/standards/sru/specs/extra-data.html">SRU
+     *      Extra Data / Extensions</a>
+     */
     public void setExtraRequestData(String name, String value) {
         if (name == null) {
@@ -143,4 +189,18 @@
 
 
+    /**
+     * Set the value of extra request parameter for this request.
+     * 
+     * @param name
+     *            the name for the extra request data parameter
+     * @return the value for the extra request data parameter or
+     *         <code>null</code> if parameter was not set
+     * @throws NullPointerException
+     *             if any required argument is <code>null</code>
+     * @throws IllegalArgumentException
+     *             if any argument is invalid
+     * @see <a href="http://www.loc.gov/standards/sru/specs/extra-data.html">SRU
+     *      Extra Data / Extensions</a>
+     */
     public String getExtraRequestData(String name) {
         if (name == null) {
@@ -150,6 +210,7 @@
             throw new IllegalArgumentException("name is an empty string");
         }
-        if (!name.startsWith("x-")) {
-            throw new IllegalArgumentException("name must start with 'x-'");
+        if (!name.startsWith(PARAM_EXTENSION_PREFIX)) {
+            throw new IllegalArgumentException("name must start with '" +
+                    PARAM_EXTENSION_PREFIX + "'");
         }
         if (extraRequestData != null) {
@@ -160,4 +221,9 @@
 
 
+    final SRUVersion getVersionPerformed() {
+        return versionPreformed;
+    }
+
+    
     final URI makeURI(SRUVersion defaultVersion)
             throws SRUClientException {
@@ -246,9 +312,12 @@
 
 
-    protected abstract SRUOperation getOperation();
-
-
-    protected abstract void addParametersToURI(URIBuilder uri)
-            throws SRUClientException;
+    /**
+     * <em>Note: this method is not a part of public API.</em>
+     * @return a constant for this
+     */
+    abstract SRUOperation getOperation();
+
+
+    abstract void addParametersToURI(URIBuilder uri) throws SRUClientException;
 
 } // class AbstractSRURequest
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUClient.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUClient.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUClient.java	(revision 2088)
@@ -1,2 +1,18 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
@@ -31,5 +47,8 @@
 import eu.clarin.sru.client.SRUScanHandler.WhereInList;
 
-
+/**
+ * A class to perform SRU operations.
+ * <p><em>This class is not thread-safe!</em></p>
+ */
 public class SRUClient {
     private static final String SRU_NS =
@@ -52,4 +71,11 @@
 
 
+    /**
+     * Constructor.
+     * 
+     * @param defaultVersion
+     *            the default version to use for SRU requests; may be overridden
+     *            by individual requests
+     */
     public SRUClient(SRUVersion defaultVersion) {
         if (defaultVersion == null) {
@@ -63,4 +89,17 @@
 
 
+    /**
+     * Register a record data parser.
+     * 
+     * @param parser
+     *            a parser instance
+     * @throws SRUClientException
+     *             if a parser handing the same record schema is already
+     *             registered
+     * @throws NullPointerException
+     *             if any required argument is <code>null</code>
+     * @throws IllegalArgumentException
+     *             if the supplied parser is invalid
+     */
     public void registerRecordParser(SRURecordDataParser parser)
             throws SRUClientException {
@@ -85,4 +124,19 @@
 
 
+    /**
+     * Perform a <em>explain</em> operation.
+     * 
+     * @param request
+     *            an instance of a {@link SRUExplainRequest} object
+     * @param handler
+     *            an instance of {@link SRUExplainHandler} to receive callbacks
+     *            when processing the result of this request
+     * @throws SRUClientException
+     *             if an unrecoverable error occurred
+     * @throws NullPointerException
+     *             if any required argument is <code>null</code>
+     * @see SRUExplainRequest
+     * @see SRUExplainHandler
+     */
     public void explain(SRUExplainRequest request, SRUExplainHandler handler)
             throws SRUClientException {
@@ -151,4 +205,19 @@
 
 
+    /**
+     * Perform a <em>scan</em> operation.
+     * 
+     * @param request
+     *            an instance of a {@link SRUScanRequest} object
+     * @param handler
+     *            an instance of {@link SRUScanHandler} to receive callbacks
+     *            when processing the result of this request
+     * @throws SRUClientException
+     *             if an unrecoverable error occurred
+     * @throws NullPointerException
+     *             if any required argument is <code>null</code>
+     * @see SRUScanRequest
+     * @see SRUScanHandler
+     */
     public void scan(SRUScanRequest request, SRUScanHandler handler)
             throws SRUClientException {
@@ -217,4 +286,19 @@
 
 
+    /**
+     * Perform a <em>searchRetreive</em> operation.
+     * 
+     * @param request
+     *            an instance of a {@link SRUSearchRetrieveRequest} object
+     * @param handler
+     *            an instance of {@link SRUSearchRetrieveHandler} to receive
+     *            callbacks when processing the result of this request
+     * @throws SRUClientException
+     *             if an unrecoverable error occurred
+     * @throws NullPointerException
+     *             if any required argument is <code>null</code>
+     * @see SRUSearchRetrieveRequest
+     * @see SRUSearchRetrieveHandler
+     */
     public void searchRetrieve(SRUSearchRetrieveRequest request,
             SRUSearchRetrieveHandler handler) throws SRUClientException {
@@ -611,5 +695,6 @@
                         SRURecordPacking packing = parseRecordPacking(reader);
 
-                        logger.debug("schema = {}, packing = {}, requested packing = {}",
+                        logger.debug("schema = {}, packing = {}, " +
+                                "requested packing = {}",
                                 new Object[] { schema, packing,
                                         request.getRecordPacking() });
@@ -617,15 +702,16 @@
                         if ((request.getRecordPacking() != null) &&
                                 (packing != request.getRecordPacking())) {
-                            logger.warn("requested '{}' record packing, but server responded with '{}' record packing",
-                                    request.getRecordPacking()
-                                            .toProtocolString(), packing
-                                            .toProtocolString());
+                            final SRURecordPacking p =
+                                    request.getRecordPacking();
+                            logger.warn("requested '{}' record packing, but " +
+                                "server responded with '{}' record packing",
+                                    p.getStringValue(),
+                                    packing.getStringValue());
                             // XXX: only throw if client is pedantic?
-                            throw new SRUClientException(
-                                    "requested '" +
-                                            request.getRecordPacking()
-                                                    .toProtocolString() +
-                                            "' record packing, but server responded with '" +
-                                            packing.toProtocolString() +
+                            throw new SRUClientException("requested '" +
+                                            p.getStringValue() +
+                                            "' record packing, but server " +
+                                            "responded with '" +
+                                            packing.getStringValue() +
                                             "' record packing");
                         }
@@ -664,4 +750,10 @@
                                     throw new SRUClientException(
                                             "error parsing record", e);
+                                }
+                                if (recordData == null) {
+                                    // FIXME: handle this better? maybe throw?
+                                    logger.warn("parse did not correctly "
+                                            + "parse the record, will skip "
+                                            + "handler callback.");
                                 }
                             } else {
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUClientException.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUClientException.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUClientException.java	(revision 2088)
@@ -1,7 +1,31 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
+/**
+ * SRU client exception. 
+ */
 @SuppressWarnings("serial")
 public class SRUClientException extends Exception {
 
+    /**
+     * Constructor
+     * 
+     * @param message an error message
+     */
     public SRUClientException(String message) {
         super(message);
@@ -9,6 +33,13 @@
 
 
-    public SRUClientException(String message, Throwable t) {
-        super(message, t);
+    /**
+     * Constructor
+     *  
+     * @param message an error message
+     * @param cause the cause of the error
+     */
+    public SRUClientException(String message, Throwable cause) {
+        super(message, cause);
     }
+
 } // class SRUClientException
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUDefaultHandler.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUDefaultHandler.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUDefaultHandler.java	(revision 2088)
@@ -1,4 +1,37 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
+/**
+ * A handler implementing all interfaces for all three response handler types.
+ * 
+ * <p>
+ * This class is available as a convenience base class for SRU applications: it
+ * implements teh three response handler interfaces:
+ * </p>
+ * <ul>
+ * <li>{@link SRUExplainHandler}</li>
+ * <li>{@link SRUScanHandler}</li>
+ * <li>{@link SRUSearchRetrieveHandler}</li>
+ * </ul>
+ * 
+ * @see SRUExplainHandler
+ * @see SRUScanHandler
+ * @see SRUSearchRetrieveHandler
+ */
 public interface SRUDefaultHandler extends SRUExplainHandler, SRUScanHandler,
         SRUSearchRetrieveHandler {
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUDefaultHandlerAdapter.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUDefaultHandlerAdapter.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUDefaultHandlerAdapter.java	(revision 2088)
@@ -1,2 +1,18 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
@@ -6,4 +22,27 @@
 import javax.xml.stream.XMLStreamReader;
 
+
+/**
+ * Default base class for SRU client response handlers.
+ * <p>
+ * This class is available as a convenience base class for SRU client
+ * applications: it provides default implementations for all of the callbacks in
+ * the three request handler handler classes:
+ * </p>
+ * <ul>
+ *  <li>{@link SRUExplainHandler}</li>
+ *  <li>{@link SRUScanHandler}</li>
+ *  <li>{@link SRUSearchRetrieveHandler}</li>
+ * </ul>
+ * <p>
+ * Application writers can extend this class when they need to implement only
+ * part of an interface; parser writers can instantiate this class to provide
+ * default handlers when the application has not supplied its own.
+ * </p>
+ * 
+ * @see SRUExplainHandler
+ * @see SRUScanHandler
+ * @see SRUSearchRetrieveHandler
+ */
 public class SRUDefaultHandlerAdapter implements SRUDefaultHandler {
     
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUDiagnostic.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUDiagnostic.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUDiagnostic.java	(revision 2088)
@@ -1,4 +1,29 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
+/**
+ * Class to hold a SRU diagnostic.
+ * 
+ * @see <a href="http://www.loc.gov/standards/sru/specs/diagnostics.html">SRU
+ *      Diagnostics</a>
+ * @see <a
+ *      href="http://www.loc.gov/standards/sru/resources/diagnostics-list.html">SRU
+ *      Diagnostics List</a>
+ */
 public final class SRUDiagnostic {
     private final String uri;
@@ -7,6 +32,18 @@
 
 
+    /**
+     * Constructor.
+     * 
+     * @param uri
+     *            the URI identifying the diagnostic
+     * @param details
+     *            supplementary information available, often in a format
+     *            specified by the diagnostic or <code>null</code>
+     * @param message
+     *            human readable message to display to the end user or
+     *            <code>null</code>
+     */
     public SRUDiagnostic(String uri, String details, String message) {
-        this.uri     = uri;
+        this.uri = uri;
         this.details = details;
         this.message = message;
@@ -14,4 +51,9 @@
 
 
+    /**
+     * Get diagnostic's identifying URI.
+     * 
+     * @return diagnostic code
+     */
     public String getURI() {
         return uri;
@@ -19,4 +61,10 @@
 
 
+    /**
+     * Get supplementary information for this diagnostic. The format for this
+     * value is often specified by the diagnostic code.
+     * 
+     * @return supplementary information
+     */
     public String getDetails() {
         return details;
@@ -24,4 +72,9 @@
 
 
+    /**
+     * Get human readable message.
+     * 
+     * @return human readable message
+     */
     public String getMessage() {
         return message;
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUExplainHandler.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUExplainHandler.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUExplainHandler.java	(revision 2088)
@@ -1,2 +1,18 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
@@ -6,12 +22,54 @@
 import javax.xml.stream.XMLStreamReader;
 
+
+/**
+ * Receive notifications to the response of a <em>explain</em> request.
+ *
+ * @see SRUExplainRequest
+ * @see <a href="http://www.loc.gov/standards/sru/specs/explain.html">SRU Explain Operation</a>
+ */
 public interface SRUExplainHandler {
 
+    /**
+     * Receive notification of diagnostics.
+     * 
+     * @param diagnostics
+     *            a list of {@link SRUDiagnostic}
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     * @see SRUDiagnostic
+     */
     public void onDiagnostics(List<SRUDiagnostic> diagnostics)
             throws SRUClientException;
 
+
+    /**
+     * Receive notification of request statistics.
+     * 
+     * @param bytes
+     *            the size of the response in bytes
+     * @param millisTotal
+     *            the total time spend processing the request
+     * @param millisNetwork
+     *            the time spend performing network operations
+     * @param millisParsing
+     *            the time spend parsing the response
+     */
     public void onRequestStatistics(int bytes, long millisTotal,
             long millisNetwork, long millisParsing);
 
+
+    /**
+     * Receive notification of extra response data.
+     * 
+     * @param reader
+     *            a {@link XMLStreamReader} to parse the extra response data
+     * @throws XMLStreamException
+     *             an error occurred while parsing the response
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     * @see <a href="http://www.loc.gov/standards/sru/specs/extra-data.html">SRU
+     *      Extra Data / Extensions</a>
+     */
     public void onExtraResponseData(XMLStreamReader reader)
             throws XMLStreamException, SRUClientException;
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUExplainRequest.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUExplainRequest.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUExplainRequest.java	(revision 2088)
@@ -1,13 +1,48 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
+/**
+ * An object for performing a <em>explain</em> operation.
+ * 
+ * @see SRUExplainHandler
+ * @see <a href="http://www.loc.gov/standards/sru/specs/explain.html">SRU Explain Operation</a>
+ */
 public final class SRUExplainRequest extends SRUAbstractRequest {
     private SRURecordPacking recordPacking;
 
 
-    protected SRUExplainRequest(String baseURI) {
+    /**
+     * Constructor.
+     * 
+     * @param baseURI
+     *            the baseURI of the endpoint
+     */
+    public SRUExplainRequest(String baseURI) {
         super(baseURI);
     }
 
 
+    /**
+     * Set the requested record packing.
+     * 
+     * @param recordPacking
+     *            the requested record packing
+     * @see SRURecordPacking
+     */
     public void setRecordPacking(SRURecordPacking recordPacking) {
         if (recordPacking == null) {
@@ -18,4 +53,10 @@
 
 
+    /**
+     * Get the requested record packing.
+     * 
+     * @return the requested record packing
+     * @see SRURecordPacking
+     */
     public SRURecordPacking getRecordPacking() {
         return recordPacking;
@@ -24,5 +65,5 @@
 
     @Override
-    protected SRUOperation getOperation() {
+    SRUOperation getOperation() {
         return SRUOperation.EXPLAIN;
     }
@@ -30,6 +71,5 @@
 
     @Override
-    protected void addParametersToURI(URIBuilder uriBuilder)
-            throws SRUClientException {
+    void addParametersToURI(URIBuilder uriBuilder) throws SRUClientException {
         // recordPacking
         if (recordPacking != null) {
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRURecordData.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRURecordData.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRURecordData.java	(revision 2088)
@@ -1,8 +1,41 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
+/**
+ * Interface for parsed record data.
+ * 
+ */
 public interface SRURecordData {
 
+    /**
+     * This record is transient. If you want to store the data to process it
+     * later, you need to create a copy of the data.
+     * 
+     * @return <code>true</code>, if record is transient,
+     *         <code>false<code> otherwis
+     */
     public boolean isTransient();
 
+
+    /**
+     * The record schema for this record.
+     * 
+     * @return the record schema
+     */
     public String getRecordSchema();
 
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRURecordDataParser.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRURecordDataParser.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRURecordDataParser.java	(revision 2088)
@@ -1,2 +1,18 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
@@ -4,8 +20,31 @@
 import javax.xml.stream.XMLStreamReader;
 
+
+/**
+ * A parser to parse record data and create appropriate Java objects.
+ * 
+ */
 public interface SRURecordDataParser {
 
+    /**
+     * The record schema this parser is able to process.
+     * 
+     * @return the record schema this parser is able to process
+     */
     public String getRecordSchema();
-    
+
+
+    /**
+     * Parse a record data into a Java object.
+     * 
+     * @param reader
+     *            a {@link XMLStreamReader} to parse the record data
+     * @return the parsed record
+     * @throws XMLStreamException
+     *             an error occurred while parsing the response
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     * @see SRURecordData
+     */
     public SRURecordData parse(XMLStreamReader reader)
             throws XMLStreamException, SRUClientException;
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRURecordPacking.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRURecordPacking.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRURecordPacking.java	(revision 2088)
@@ -1,17 +1,45 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
+/**
+ * SRU Record packing
+ */
 public enum SRURecordPacking {
-    XML, STRING;
+    /**
+     * XML record packing
+     */
+    XML {
+        @Override
+        String getStringValue() {
+            return "xml";
+        }
+    },
 
-    public String toProtocolString() {
-        switch (this) {
-        case XML:
-            return "xml";
-        case STRING:
+    /**
+     * String record packing
+     */
+    STRING {
+        @Override
+        String getStringValue() {
             return "string";
-        default:
-            return null;
         }
-    }
+    };
+
+    abstract String getStringValue();
 
 } // enum SRURecordPacking
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUScanHandler.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUScanHandler.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUScanHandler.java	(revision 2088)
@@ -1,2 +1,18 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
@@ -6,25 +22,138 @@
 import javax.xml.stream.XMLStreamReader;
 
+
+/**
+ * Receive notifications to the response of a <em>scan</em> request.
+ * 
+ * @see SRUScanRequest
+ * @see <a href="http://www.loc.gov/standards/sru/specs/scan.html">SRU
+ *      Scan Operation</a>
+ */
 public interface SRUScanHandler {
+    /**
+     * A flag to indicate the position of the term within the complete term
+     * list.
+     */
     public enum WhereInList {
-        FIRST, LAST, ONLY, INNER;
+        /**
+         * The first term (<em>first</em>)
+         */
+        FIRST,
+
+        /**
+         * The last term (<em>last</em>)
+         */
+        LAST,
+
+        /**
+         * The only term (<em>only</em>)
+         */
+        ONLY,
+
+        /**
+         * Any other term (<em>inner</em>)
+         */
+        INNER;
     }
 
+
+    /**
+     * Receive notification of diagnostics.
+     * 
+     * @param diagnostics
+     *            a list of {@link SRUDiagnostic}
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     * @see SRUDiagnostic
+     */
     public void onDiagnostics(List<SRUDiagnostic> diagnostics)
             throws SRUClientException;
 
+
+    /**
+     * Receive notification of request statistics.
+     * 
+     * @param bytes
+     *            the size of the response in bytes
+     * @param millisTotal
+     *            the total time spend processing the request
+     * @param millisNetwork
+     *            the time spend performing network operations
+     * @param millisParsing
+     *            the time spend parsing the response
+     */
     public void onRequestStatistics(int bytes, long millisTotal,
             long millisNetwork, long millisParsing);
 
+
+    /**
+     * Receive notification of extra response data.
+     * 
+     * @param reader
+     *            a {@link XMLStreamReader} to parse the extra response data
+     * @throws XMLStreamException
+     *             an error occurred while parsing the response
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     * @see <a href="http://www.loc.gov/standards/sru/specs/extra-data.html">SRU
+     *      Extra Data / Extensions</a>
+     */
     public void onExtraResponseData(XMLStreamReader reader)
             throws XMLStreamException, SRUClientException;
 
+
+    /**
+     * Receive notifications of the start of the enumeration of terms in the
+     * response.
+     * 
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     */
     public void onStartTerms() throws SRUClientException;
 
+
+    /**
+     * Receive notifications of the end of the enumeration of terms in the
+     * response.
+     * 
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     */
     public void onFinishTerms() throws SRUClientException;
 
+
+    /**
+     * Receive notification of a term.
+     * 
+     * @param value
+     *            the term (exactly) as it appears in the index
+     * @param numberOfRecords
+     *            the number of records for the current term which would be
+     *            matched
+     * @param displayTerm
+     *            a string for the current term to display to the end user in
+     *            place of the term itself or <code>null</code> if not available
+     * @param whereInList
+     *            a flag to indicate the position of the term within the
+     *            complete term list or <code>null</code> of not available
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     */
     public void onTerm(String value, int numberOfRecords, String displayTerm,
             WhereInList whereInList) throws SRUClientException;
 
+
+    /**
+     * Receive notification of extra term data.
+     * 
+     * @param value
+     *            the term (exactly) as it appears in the index
+     * @param reader
+     *            a {@link XMLStreamReader} to parse the extra term data
+     * @throws XMLStreamException
+     *             an error occurred while parsing the response
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     */
     public void onExtraTermData(String value, XMLStreamReader reader)
             throws XMLStreamException, SRUClientException;
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUScanRequest.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUScanRequest.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUScanRequest.java	(revision 2088)
@@ -1,4 +1,31 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
+/**
+ * An object for performing a <em>explain</em> operation.
+ * <p>The following argument arguments are mandatory:</p>
+ * <ul>
+ *   <li><em>scanClause</em></li>
+ * </ul>
+ * 
+ * @see SRUScanHandler
+ * @see <a href="http://www.loc.gov/standards/sru/specs/scan.html">SRU Scan
+ *      Operation</a>
+ */
 public final class SRUScanRequest extends SRUAbstractRequest {
     private String scanClause;
@@ -7,9 +34,21 @@
 
 
-    protected SRUScanRequest(String baseURI) {
+    /**
+     * Constructor.
+     * 
+     * @param baseURI
+     *            the baseURI of the endpoint
+     */
+    public SRUScanRequest(String baseURI) {
         super(baseURI);
     }
 
 
+    /**
+     * Get the value of the <em>scanClause</em> argument for this request.
+     * 
+     * @return the value for the <em>scanClause</em> argument or
+     *         <code>null</code> of none was set
+     */
     public String getScanClause() {
         return scanClause;
@@ -17,4 +56,14 @@
 
 
+    /**
+     * Set the value of the <em>scanClause</em> argument for this request.
+     * 
+     * @param scanClause
+     *            the value for the <em>scanClause</em> argument
+     * @throws NullPointerException
+     *             if any required argument is <code>null</code>
+     * @throws IllegalArgumentException
+     *             if any argument is invalid
+     */
     public void setScanClause(String scanClause) {
         if (scanClause == null) {
@@ -28,4 +77,9 @@
 
 
+    /**
+     * Get the value of the <em>responsePosition</em> argument for this request.
+     * 
+     * @return the value for the <em>responsePosition</em> argument
+     */
     public int getResponsePosition() {
         return responsePosition;
@@ -33,4 +87,12 @@
 
 
+    /**
+     * Set the value of the <em>responsePosition</em> argument for this request.
+     * 
+     * @param responsePosition
+     *            the value for the <em>responsePosition</em> argument
+     * @throws IllegalArgumentException
+     *             if any argument is invalid
+     */
     public void setResponsePosition(int responsePosition) {
         if (responsePosition < 0) {
@@ -41,4 +103,9 @@
 
 
+    /**
+     * Get the value of the <em>maximumTerms</em> argument for this request.
+     * 
+     * @return the value for the <em>maximumTerms</em> argument
+     */
     public int getMaximumTerms() {
         return maximumTerms;
@@ -46,4 +113,12 @@
 
 
+    /**
+     * Set the value of the <em>maximumTerms</em> argument for this request.
+     * 
+     * @param maximumTerms
+     *            the value for the <em>maximumTerms</em> argument
+     * @throws IllegalArgumentException
+     *             if any argument is invalid
+     */
     public void setMaximumTerms(int maximumTerms) {
         if (maximumTerms < 0) {
@@ -55,5 +130,5 @@
 
     @Override
-    protected SRUOperation getOperation() {
+    SRUOperation getOperation() {
         return SRUOperation.SCAN;
     }
@@ -61,6 +136,5 @@
 
     @Override
-    protected void addParametersToURI(URIBuilder uriBuilder)
-            throws SRUClientException {
+    void addParametersToURI(URIBuilder uriBuilder) throws SRUClientException {
         // scanClause
         if ((scanClause == null) || scanClause.isEmpty()) {
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUSearchRetrieveHandler.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUSearchRetrieveHandler.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUSearchRetrieveHandler.java	(revision 2088)
@@ -1,2 +1,18 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
@@ -6,27 +22,141 @@
 import javax.xml.stream.XMLStreamReader;
 
+
+/**
+ * Receive notifications to the response of a <em>searchRetrieve</em> request.
+ * 
+ * @see SRUSearchRetrieveRequest
+ * @see <a href="http://www.loc.gov/standards/sru/specs/search-retrieve.html">
+ *      SRU SearchRetrieve Operation</a>
+ */
 public interface SRUSearchRetrieveHandler {
 
+    /**
+     * Receive notification of diagnostics.
+     * 
+     * @param diagnostics
+     *            a list of {@link SRUDiagnostic}
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     * @see SRUDiagnostic
+     */
     public void onDiagnostics(List<SRUDiagnostic> diagnostics)
             throws SRUClientException;
 
+
+    /**
+     * Receive notification of request statistics.
+     * 
+     * @param bytes
+     *            the size of the response in bytes
+     * @param millisTotal
+     *            the total time spend processing the request
+     * @param millisNetwork
+     *            the time spend performing network operations
+     * @param millisParsing
+     *            the time spend parsing the response
+     */
     public void onRequestStatistics(int bytes, long millisTotal,
             long millisNetwork, long millisParsing);
 
+
+    /**
+     * Receive notification of extra response data.
+     * 
+     * @param reader
+     *            a {@link XMLStreamReader} to parse the extra response data
+     * @throws XMLStreamException
+     *             an error occurred while parsing the response
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     * @see <a href="http://www.loc.gov/standards/sru/specs/extra-data.html">SRU
+     *      Extra Data / Extensions</a>
+     */
     public void onExtraResponseData(XMLStreamReader reader)
             throws XMLStreamException, SRUClientException;
 
+
+    /**
+     * Receive notifications of the start of the enumeration of records in the
+     * response.
+     * 
+     * @param numberOfRecords
+     *            the number of records or <code>-1</code> if not available
+     * @param resultSetId
+     *            the result set id or <code>-1</code> if not available
+     * @param resultSetIdleTime
+     *            the result set idle time or <code>-1</code> if not available
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     */
     public void onStartRecords(int numberOfRecords, int resultSetId,
             int resultSetIdleTime) throws SRUClientException;
 
+
+    /**
+     * Receive notifications of the end of the enumeration of records in the
+     * response.
+     * 
+     * @param nextRecordPosition
+     *            the next record position or <code>-1</code> if not available
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     */
     public void onFinishRecords(int nextRecordPosition)
             throws SRUClientException;
 
+
+    /**
+     * Receive notification of a record in the result set.
+     * 
+     * @param identifier
+     *            identifier of the record or <code>null</code> if not available
+     * @param position
+     *            position of the record in the result set ot <code>-1</code> if
+     *            not available
+     * @param data
+     *            the parsed record data
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     * @see SRURecordData
+     * @see SRURecordDataParser
+     */
     public void onRecord(String identifier, int position, SRURecordData data)
             throws SRUClientException;
 
+
+    /**
+     * Receive notification of a surrogate record in the result set.
+     * 
+     * @param identifier
+     *            identifier of the record or <code>null</code> if not available
+     * @param position
+     *            position of the record in the result set ot <code>-1</code> if
+     *            not available
+     * @param data
+     *            the surrogate record data, i.e. a diagnostic
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     * @see SRUDiagnostic
+     */
     public void onSurrogateRecord(String identifier, int position,
             SRUDiagnostic data) throws SRUClientException;
 
+
+    /**
+     * Receive notification of extra record data.
+     * 
+     * @param identifier
+     *            identifier of the record or <code>null</code> if not available
+     * @param position
+     *            position of the record in the result set ot <code>-1</code> if
+     *            not available
+     * @param reader
+     *            a {@link XMLStreamReader} to parse the extra term data
+     * @throws XMLStreamException
+     *             an error occurred while parsing the response
+     * @throws SRUClientException
+     *             any SRU exception, possibly wrapping another exception
+     */
     public void onExtraRecordData(String identifier, int position,
             XMLStreamReader reader) throws XMLStreamException,
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUSearchRetrieveRequest.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUSearchRetrieveRequest.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUSearchRetrieveRequest.java	(revision 2088)
@@ -1,4 +1,33 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
+/**
+ * An object for performing a <em>explain</em> operation.
+ * <p>
+ * The following argument arguments are mandatory:
+ * </p>
+ * <ul>
+ * <li><em>query</em></li>
+ * </ul>
+ * 
+ * @see SRUSearchRetrieveHandler
+ * @see <a href="http://www.loc.gov/standards/sru/specs/search-retrieve.html">
+ *      SRU SearchRetrieve Operation</a>
+ */
 public final class SRUSearchRetrieveRequest extends SRUAbstractRequest {
     private String query;
@@ -10,9 +39,21 @@
 
 
-    protected SRUSearchRetrieveRequest(String baseURI) {
+    /**
+     * Constructor.
+     * 
+     * @param baseURI
+     *            the baseURI of the endpoint
+     */
+    public SRUSearchRetrieveRequest(String baseURI) {
         super(baseURI);
     }
 
 
+    /**
+     * Get the value of the <em>query</em> argument for this request.
+     * 
+     * @return the value for the <em>query</em> argument or <code>null</code> of
+     *         none was set
+     */
     public String getQuery() {
         return query;
@@ -20,4 +61,14 @@
 
 
+    /**
+     * Set the value of the <em>query</em> argument for this request.
+     * 
+     * @param query
+     *            the value for the <em>query</em> argument
+     * @throws NullPointerException
+     *             if any required argument is <code>null</code>
+     * @throws IllegalArgumentException
+     *             if any argument is invalid
+     */
     public void setQuery(String query) {
         if (query == null) {
@@ -31,4 +82,10 @@
 
 
+    /**
+     * Get the value of the <em>startRecord</em> argument for this request.
+     * 
+     * @return the value for the <em>startRecord</em> argument or
+     *         <code>-1</code> of none was set
+     */
     public int getStartRecord() {
         return startRecord;
@@ -36,4 +93,12 @@
 
 
+    /**
+     * Set the value of the <em>startRecord</em> argument for this request.
+     * 
+     * @param startRecord
+     *            the value for the <em>startRecord</em> argument
+     * @throws IllegalArgumentException
+     *             if any argument is invalid
+     */
     public void setStartRecord(int startRecord) {
         if (startRecord < 1) {
@@ -44,4 +109,10 @@
 
 
+    /**
+     * Get the value of the <em>maximumRecords</em> argument for this request.
+     * 
+     * @return the value for the <em>maximumRecords</em> argument or
+     *         <code>-1</code> of none was set
+     */
     public int getMaximumRecords() {
         return maximumRecords;
@@ -49,4 +120,12 @@
 
 
+    /**
+     * Set the value of the <em>maximumRecords</em> argument for this request.
+     * 
+     * @param maximumRecords
+     *            the value for the <em>maximumRecords</em> argument
+     * @throws IllegalArgumentException
+     *             if any argument is invalid
+     */
     public void setMaximumRecords(int maximumRecords) {
         if (maximumRecords < 0) {
@@ -57,4 +136,10 @@
 
 
+    /**
+     * Get the value of the <em>recordSchema</em> argument for this request.
+     * 
+     * @return the value for the <em>recordSchema</em> argument or
+     *         <code>null</code> of none was set
+     */
     public String getRecordSchema() {
         return recordSchema;
@@ -62,4 +147,14 @@
 
 
+    /**
+     * Set the value of the <em>recordSchema</em> argument for this request.
+     * 
+     * @param recordSchema
+     *            the value for the <em>recordSchema</em> argument
+     * @throws NullPointerException
+     *             if any required argument is <code>null</code>
+     * @throws IllegalArgumentException
+     *             if any argument is invalid
+     */
     public void setRecordSchema(String recordSchema) {
         this.recordSchema = recordSchema;
@@ -67,4 +162,23 @@
 
 
+    /**
+     * Get the value of the <em>recordSchema</em> argument for this request.
+     * 
+     * @return the value for the <em>recordSchema</em> argument or
+     *         <code>null</code> of none was set
+     */
+    public SRURecordPacking getRecordPacking() {
+        return recordPacking;
+    }
+
+
+    /**
+     * Set the value of the <em>recordPacking</em> argument for this request.
+     * 
+     * @param recordPacking
+     *            the value for the <em>recordPacking</em> argument
+     * @throws NullPointerException
+     *             if any required argument is <code>null</code>
+     */
     public void setRecordPacking(SRURecordPacking recordPacking) {
         if (recordPacking == null) {
@@ -75,9 +189,10 @@
 
 
-    public SRURecordPacking getRecordPacking() {
-        return recordPacking;
-    }
-
-
+    /**
+     * Get the value of the <em>resultSetTTL</em> argument for this request.
+     * 
+     * @return the value for the <em>resultSetTTL</em> argument or
+     *         <code>-1</code> of none was set
+     */
     public int getResultSetTTL() {
         return resultSetTTL;
@@ -85,4 +200,12 @@
 
 
+    /**
+     * Set the value of the <em>resultSetTTL</em> argument for this request.
+     * 
+     * @param resultSetTTL
+     *            the value for the <em>resultSetTTL</em> argument
+     * @throws IllegalArgumentException
+     *             if any argument is invalid
+     */
     public void setResultSetTTL(int resultSetTTL) {
         this.resultSetTTL = resultSetTTL;
@@ -91,5 +214,5 @@
 
     @Override
-    protected SRUOperation getOperation() {
+    SRUOperation getOperation() {
         return SRUOperation.SEARCH_RETRIEVE;
     }
@@ -97,6 +220,5 @@
 
     @Override
-    protected void addParametersToURI(URIBuilder uriBuilder)
-            throws SRUClientException {
+    void addParametersToURI(URIBuilder uriBuilder) throws SRUClientException {
         // query
         if ((query == null) || query.isEmpty()) {
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUVersion.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUVersion.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUVersion.java	(revision 2088)
@@ -1,6 +1,16 @@
 package eu.clarin.sru.client;
 
+/**
+ * SRU version
+ */
 public enum SRUVersion {
+    /**
+     * SRU/CQL version 1.1
+     */
     VERSION_1_1,
-    VERSION_1_2
+
+    /**
+     * SRU/CQL version 1.2
+     */
+    VERSION_1_2;
 } // enum SRUVersion
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUXMLStreamReader.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUXMLStreamReader.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/SRUXMLStreamReader.java	(revision 2088)
@@ -1,2 +1,18 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/TestClient.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/TestClient.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/TestClient.java	(revision 2088)
@@ -1,2 +1,18 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
@@ -25,4 +41,9 @@
             }
 
+            /*
+             * just use one dump handler for each request.
+             * A real application should be smarter here and use the
+             * appropriate handler 
+             */
             SRUDefaultHandlerAdapter handler = new SRUDefaultHandlerAdapter() {
                 @Override
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/XmlStreamReaderProxy.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/XmlStreamReaderProxy.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/XmlStreamReaderProxy.java	(revision 2088)
@@ -1,2 +1,18 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/client/XmlStreamReaderUtils.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/client/XmlStreamReaderUtils.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/client/XmlStreamReaderUtils.java	(revision 2088)
@@ -1,2 +1,18 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.client;
 
@@ -5,4 +21,11 @@
 import javax.xml.stream.XMLStreamReader;
 
+
+/**
+ * Helper class for dealing with {@link XMLStreamReader}.
+ * <p>
+ * <em>Note: this class is semi-public API and may be change or removed in the future.</em>
+ * </p>
+ */
 public final class XmlStreamReaderUtils {
     private XmlStreamReaderUtils() {
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/fcs/ClarinFederatedContentSearchRecordData.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/fcs/ClarinFederatedContentSearchRecordData.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/fcs/ClarinFederatedContentSearchRecordData.java	(revision 2088)
@@ -1,6 +1,27 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.fcs;
 
 import eu.clarin.sru.client.SRURecordData;
 
+
+/**
+ * A record parse to parse records conforming to CLARIN FCS specification. The
+ * parser currently supports the KWIC view.
+ */
 public final class ClarinFederatedContentSearchRecordData implements
         SRURecordData {
@@ -10,11 +31,13 @@
     private String right;
 
+
     ClarinFederatedContentSearchRecordData(String pid, String left,
             String keyword, String right) {
-        this.pid   = pid;
-        this.left  = left;
-        this.keyword   = keyword;
+        this.pid = pid;
+        this.left = left;
+        this.keyword = keyword;
         this.right = right;
     }
+
 
     @Override
@@ -23,24 +46,29 @@
     }
 
+
     @Override
     public String getRecordSchema() {
         return ClarinFederatedContentSearchRecordParser.FCS_NS;
     }
-    
+
+
     public String getPid() {
         return pid;
     }
 
+
     public String getLeft() {
         return left;
     }
-    
+
+
     public String getKeyword() {
         return keyword;
     }
-    
+
+
     public String getRight() {
         return right;
     }
-    
+
 } // class ClarinFederatedContentSearchRecordData
Index: /SRUClient/trunk/src/main/java/eu/clarin/sru/fcs/ClarinFederatedContentSearchRecordParser.java
===================================================================
--- /SRUClient/trunk/src/main/java/eu/clarin/sru/fcs/ClarinFederatedContentSearchRecordParser.java	(revision 2087)
+++ /SRUClient/trunk/src/main/java/eu/clarin/sru/fcs/ClarinFederatedContentSearchRecordParser.java	(revision 2088)
@@ -1,2 +1,18 @@
+/**
+ * This software is copyright (c) 2011 by
+ *  - Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ * This is free software. You can redistribute it
+ * and/or modify it under the terms described in
+ * the GNU General Public License v3 of which you
+ * should have received a copy. Otherwise you can download
+ * it from
+ *
+ *   http://www.gnu.org/licenses/gpl-3.0.txt
+ *
+ * @copyright Institut fuer Deutsche Sprache (http://www.ids-mannheim.de)
+ *
+ * @license http://www.gnu.org/licenses/gpl-3.0.txt
+ *  GNU General Public License v3
+ */
 package eu.clarin.sru.fcs;
 
@@ -12,4 +28,8 @@
 import eu.clarin.sru.client.XmlStreamReaderUtils;
 
+
+/**
+ * A record for CLARIN FCS.
+ */
 public class ClarinFederatedContentSearchRecordParser implements
         SRURecordDataParser {
@@ -21,5 +41,5 @@
     private static final String DATAVIEW_KWIC = "kwic";
 
-    
+
     @Override
     public String getRecordSchema() {
@@ -27,22 +47,25 @@
     }
 
-    
+
     @Override
     public SRURecordData parse(XMLStreamReader reader)
             throws XMLStreamException, SRUClientException {
         XmlStreamReaderUtils.readStart(reader, FCS_NS, "Resource", true, true);
-        String pid = XmlStreamReaderUtils.readAttributeValue(reader, null, "pid");
+        String pid = XmlStreamReaderUtils.readAttributeValue(reader, null,
+                "pid");
         XmlStreamReaderUtils.consumeStart(reader);
-        
-        String left    = null;
+
+        String left = null;
         String keyword = null;
-        String right   = null;
+        String right = null;
 
         boolean first = true;
         boolean kwic = false;
-        
-        while (XmlStreamReaderUtils.readStart(reader, FCS_NS, "DataView", first, true)) {
+
+        while (XmlStreamReaderUtils.readStart(reader, FCS_NS, "DataView",
+                first, true)) {
             first = false;
-            String type = XmlStreamReaderUtils.readAttributeValue(reader, null, "type");
+            String type = XmlStreamReaderUtils.readAttributeValue(reader, null,
+                    "type");
             XmlStreamReaderUtils.consumeStart(reader);
             if ((type == null) || type.isEmpty()) {
@@ -53,13 +76,18 @@
             if (DATAVIEW_KWIC.equals(type)) {
                 if (kwic) {
-                    throw new SRUClientException("only one KWIC dataview is allowed");
+                    throw new SRUClientException(
+                            "only one KWIC dataview is allowed");
                 }
-                XmlStreamReaderUtils.readStart(reader, FCS_KWIC_NS, "kwic", true);
-                if (XmlStreamReaderUtils.readStart(reader, FCS_KWIC_NS, "c", false)) {
+                XmlStreamReaderUtils.readStart(reader, FCS_KWIC_NS, "kwic",
+                        true);
+                if (XmlStreamReaderUtils.readStart(reader, FCS_KWIC_NS, "c",
+                        false)) {
                     left = XmlStreamReaderUtils.readString(reader, false);
                     XmlStreamReaderUtils.readEnd(reader, FCS_KWIC_NS, "c");
                 }
-                keyword = XmlStreamReaderUtils.readContent(reader, FCS_KWIC_NS, "kw", true);
-                if (XmlStreamReaderUtils.readStart(reader, FCS_KWIC_NS, "c", false)) {
+                keyword = XmlStreamReaderUtils.readContent(reader, FCS_KWIC_NS,
+                        "kw", true);
+                if (XmlStreamReaderUtils.readStart(reader, FCS_KWIC_NS, "c",
+                        false)) {
                     right = XmlStreamReaderUtils.readString(reader, false);
                     XmlStreamReaderUtils.readEnd(reader, FCS_KWIC_NS, "c");
