--- a/LTPDAConnectionManager.m	Sun May 23 22:12:05 2010 +0200
+++ b/LTPDAConnectionManager.m	Mon May 24 00:14:37 2010 +0200
@@ -18,11 +18,22 @@
   methods(Static)
 
     function reset()
-      setappdata(0, LTPDAConnectionManager.appdataKey, []);
+    % RESET Resets the state of the connection manager.
+    %
+    % This static method removes the LTPDAConnectionManager instance data from
+    % the appdata storage. Causes the reset of the credentials cache and the
+    % removal of all the connections from the connection pool.
+
+      rmappdata(0, LTPDAConnectionManager.appdataKey);
     end
 
+
     function key = appdataKey()
-      % defined as static method to be acessible by the reset static method
+    % APPDATAKEY Returns the key used to store instance data in appdata.
+    %
+    % This is defined as static method, and not has an instance constant
+    % property, to to be accessible by the reset static method.
+
       key = 'LTPDAConnectionManager';
     end
 
@@ -30,7 +41,18 @@
 
   methods
 
-    function cm = LTPDAConnectionManager(pl)
+    function cm = LTPDAConnectionManager()
+    % LTPDACONNECTIONMANAGER Manages credentials and database connections.
+    %
+    % This constructor returns an handler to a LTPDAConnectionManager class
+    % instance. Database connections can be obtained trough the obtained
+    % object with the connect() method.
+    %
+    % The purpose of this class it to keep track of open database connections
+    % and to cache database credentials. It must be used in all LTPDA toolbox
+    % functions that required to obtain database connections. Its behaviour can
+    % be configured via LTPDA toolbox user preferences. The object status is
+    % persisted trough the appdata matlab facility.
 
       % load state from appdata
       acm = getappdata(0, cm.appdataKey());
@@ -73,7 +95,14 @@
 
 
     function n = count(cm)
+    % COUNT Returns the number of open connections in the connections pool.
+    %
+    % This method has the side effect of removing all closed connections from
+    % the connections pool, so that the underlying objects can be garbage
+    % collected.
+
       import utils.const.*
+
       % find closed connections in the pool
       mask = false(numel(cm.connections), 1);
       for kk = 1:numel(cm.connections)
@@ -90,14 +119,31 @@
       n = numel(cm.connections);
     end
 
-
     function clear(cm)
-      % remove all cached credentials
+    % CLEAR Removes all cached credentials from the connection manager.
       cm.credentials = {};
     end
 
 
     function conn = connect(cm, varargin)
+    % CONNECT Uses provided credential to establish a database connection.
+    %
+    % CONNECT(hostname, database, username, password) Returns an object
+    % implementing the java.sql.Connection interface handing a connection to
+    % the specified database. Any of the parameter is optional. The user will
+    % be queried for the missing information.
+    %
+    % The returned connection are added to a connections pool. When the number
+    % of connections in the pool exceeds a configurable maximum, no more
+    % connection are instantiated. Closed connections are automatically
+    % removed from the pool.
+    %
+    % CONNECT(pl) Works as the above but the parameters are obtained from the
+    % plist object PL. If the 'connection' parameter in the plist contains an
+    % object implementing the java.sql.Connection interface, this object is
+    % returned instead that opening a new connection. In this case the
+    % connection in not added to the connection pool.
+
       import utils.const.*
 
       % save current credentials cache
@@ -162,6 +208,16 @@
 
 
     function close(cm, ids)
+    % CLOSE Forces connections to be closed.
+    %
+    % In the case bugs in other routines working with database connections
+    % produce orphan connections, this method can be used to force the close
+    % of those connections.
+    %
+    % CLOSE(ids) Closes the connections with the corresponding IDs in the
+    % connections pool. If no ID is given all connections in the pool are
+    % closed.
+
       if nargin < 2
         ids = 1:numel(cm.connections);
       end
@@ -170,9 +226,18 @@
 
 
     function add(cm, c)
+    % ADD Adds credentials to the credentials cache.
+    %
+    % This method can be used to initialize or add to the cache, credentials
+    % that will be used in subsequent connections attempts. This method accepts
+    % only credentials in the form of utils.jmysql.credentials objects.
+
+      % check input arguments
       if nargin < 2 || ~isa(c, 'credentials')
         error('### invalid call');
       end
+
+      % add to the cache
       cm.cacheCredentials(c);
     end
 
@@ -181,9 +246,11 @@
   methods(Access=private)
 
     function conn = getConnection(cm, varargin)
+    % GETCONNECTION Where the implementation of the connect method really is.
 
       import utils.const.*
 
+      % handle variable number of arguments
       switch numel(varargin)
         case 0
           [hostname, database, username] = cm.selectDatabase();
@@ -257,6 +324,8 @@
 
 
     function ids = findCredentialsId(cm, varargin)
+    % FINDCREDENTIALSID Find credentials in the cache and returns their IDs.
+
       import utils.const.*
       ids = [];
 
@@ -277,6 +346,8 @@
 
 
     function cred = findCredentials(cm, varargin)
+    % FINDCREDENTIALS Find credentials in the cache and returns them in a list.
+
       % default
       cred = [];
 
@@ -291,6 +362,8 @@
 
 
     function cacheCredentials(cm, c)
+    % CACHECREDENTIALS Adds to or updates the credentials cache.
+
       import utils.const.*
 
       % find entry to update
@@ -324,7 +397,9 @@
 
 
     function [username, password, cache] = inputCredentials(cm, cred)
-      % this is a stubb
+    % INPUTCREDENTIALS Queries the user for database username and password.
+
+      % this is a stubb that must be replaced by a graphical interface
 
       % build a cell array of usernames and passwords
       users = { cred(:).username };
@@ -360,7 +435,9 @@
 
 
     function [hostname, database, username] = selectDatabase(cm)
-      % this is a stubb
+    % SELECTDATABASE Makes the user choose to which database connect to.
+
+      % this is a stubb that must be replaced by a graphical interface
 
       for kk = 1:numel(cm.credentials)
         fprintf('% 2d.  %s\n', char(cm.credentials{kk}));
@@ -388,8 +465,15 @@
 end % classdef
 
 
-% this should become utils.jmysql.connect
 function conn = connect(hostname, database, username, password)
+% CONNECT Opens a connection to the given database.
+%
+% This function returns a Java object implementing the java.sql.Connection
+% interface connected to the given database using the provided credentials.
+% If the connection fails because the given username and password pair is not
+% accepted by the server an utils:jmysql:connect:AccessDenied error is thrown.
+
+  % this should become utils.jmysql.connect
 
   % informative message
   import utils.const.*