# HG changeset patch
# User Daniele Nicolodi <daniele@science.unitn.it>
# Date 1274645525 -7200
# Node ID b4f2f4c10918a8a8a24189ff6c28b67cf1f5463e
# Parent  b71833fb33efecd4a5b4e160fa934b6fbbe2c390
Add help comments.

diff -r b71833fb33ef -r b4f2f4c10918 credentials.m
--- a/credentials.m	Sun May 23 22:09:23 2010 +0200
+++ b/credentials.m	Sun May 23 22:12:05 2010 +0200
@@ -1,18 +1,28 @@
 classdef credentials
+
   properties
-  
+
     hostname = [];
     database = [];
     username = [];
     password = [];
     expiry = 0;
-    
+
   end % properties
 
   methods
 
-    % contructor
     function obj = credentials(hostname, database, username, password)
+    % CREDENTIALS Constructor for credentials objects.
+    %
+    % Those are simple container objects to hold credentials required for
+    % establishing a connection to a database server, in addition to an
+    % expiry time.
+    %
+    % CREDENTIALS(hostname, database, username, password) The constructor can
+    % be called with any number of arguments. The default value for the object
+    % properties is the empty vector.
+
       switch nargin
         case 1
           obj.hostname = hostname;
@@ -31,22 +41,28 @@
       end
     end
 
-    % convert to string representation
     function str = char(obj, mode)
+    % CHAR Convert a credentials object to string representation.
+    %
+    % It takes an optional second argument that defines the representation to
+    % use. The default is to replace the password, if present, with the YES
+    % string, other possible modes are SHORT where password is omitted, or FULL
+    % where the password is shown at it is.
+
       if nargin < 2
         mode = '';
       end
       switch mode
         case 'short'
           % do not show password
-          frm = 'mysql://%s/%s username=%s';  
+          frm = 'mysql://%s/%s username=%s';
           str = sprintf(frm, obj.hostname, obj.database, obj.username);
         case 'full'
           % show password
           frm = 'mysql://%s/%s username=%s password=%s';
           str = sprintf(frm, obj.hostname, obj.database, obj.username, obj.password);
         otherwise
-          % by default only show if a password is known              
+          % by default only show if a password is known
           passwd = [];
           if ischar(obj.password)
             passwd = 'YES';
@@ -55,41 +71,70 @@
           str = sprintf(frm, obj.hostname, obj.database, obj.username, passwd);
       end
     end
-    
-    % display
+
     function disp(obj)
+    % DISP Overloaded display method for credentials objects.
+    %
+    % Uses the default string representation of the char() method where the
+    % password, if present, is replaced with the string YES.
+
       disp(['    ' char(obj) char(10)]);
     end
-    
-    % check that a credentials object contails all the required informations
+
     function rv = complete(obj)
-      info = {'hostname', 'database', 'username', 'password'};
+    % COMPLETE Checks if the credentials are complete.
+    %
+    % Credentials object are complete when they contains all the required
+    % information to connect to a database. Namely the HOSTNAME, DATABASE
+    % and USERNAME properties should not be empty, the PASSWORD property is
+    % allowed to be an empty string '' but not [].
+
+      info = {'hostname', 'database', 'username'};
       for kk = 1:numel(info)
         if isempty(obj.(info{kk}))
           rv = false;
           return;
         end
       end
+      if ~ischar(obj.password)
+        rv = false;
+        return;
+      end
       rv = true;
     end
-    
-    % check if the credentials are expired
+
     function rv = expired(obj)
+    % EXPIRED Checks if the credentials are expired.
+    %
+    % Credential objects expire when their expiry time is smaller than the
+    % current time in seconds since the epoch, as obtained by the time()
+    % function. Credentials with zero or negative expiry time never expire.
+
       rv = false;
       if obj.expiry > 0 && double(time()) > obj.expiry
         rv = true;
       end
     end
-    
-    % check if the credentials object matches the given informations
+
     function rv = match(obj, hostname, database, username)
+    % MATCH Check if the credentials object matches the given information.
+    %
+    % MATCH(obj, hostname, database) Returns true when HOSTANAME and DATABASE
+    % parameters match the object properties.
+    %
+    % MATCH(obj, hostname, database, username) Returns true when HOSTANAME,
+    % DATABASE, and USERNAME parameters match the object
+    % properties. USERNAME is compared only if both the given one and the
+    % object property are not the empty vector.
+
+      % default arguments
       if nargin < 4
         username = [];
       end
-      
-      % default value
+
+      % default return value
       rv = true;
-      
+
       if ~strcmp(obj.hostname, hostname)
         rv = false;
         return;
@@ -103,7 +148,7 @@
         return;
       end
     end
-    
+
   end % methods
 
 end
\ No newline at end of file