remove method login(), update documentation

SeedDMS_Core/Core/inc.ClassDMS.php

@@ -43,15 +43,16 @@ require_once("inc.ClassAttribute.php");
  * by design. It is up to the calling application to use the methods
  * {@link SeedDMS_Core_Folder::getAccessMode()} and
  * {@link SeedDMS_Core_Document::getAccessMode()} and interpret them as desired.
- * Though, there are two convinient functions to filter a list of
+ * Though, there are two convenient functions to filter a list of
  * documents/folders for which users have access rights for. See
- * {@link SeedDMS_Core_DMS::filterAccess()}
- * and {@link SeedDMS_Core_DMS::filterUsersByAccess()}
+ * {@link filterAccess()}
+ * and {@link filterUsersByAccess()}
  *
- * Though, this class has two methods to set the currently logged in user
- * ({@link setUser} and {@link login}), none of them need to be called, because
+ * Though, this class has a method to set the currently logged in user
+ * ({@link setUser}), it does not have to be called, because
  * there is currently no class within the SeedDMS core which needs the logged
- * in user.
+ * in user. {@link SeedDMS_Core_DMS} itself does not do any user authentication.
+ * It is up to the application using this class.
  *
  * <code>
  * <?php
@@ -149,11 +150,12 @@ class SeedDMS_Core_DMS {
 
 
 	/**
-	 * Checks if two objects are equal by comparing its ID
+	 * Checks if two objects are equal by comparing their IDs
 	 *
 	 * The regular php check done by '==' compares all attributes of
-	 * two objects, which isn't required. The method will first check
-	 * if the objects are instances of the same class.
+	 * two objects, which is often not required. The method will first check
+	 * if the objects are instances of the same class and than if they
+	 * have the same id.
 	 *
 	 * @param object $object1 first object to be compared
 	 * @param object $object2 second object to be compared
@@ -168,11 +170,12 @@ class SeedDMS_Core_DMS {
 	} /* }}} */
 
 	/**
-	 * Checks if a list of objects contains a single object 
+	 * Checks if a list of objects contains a single object by comparing their IDs
 	 *
 	 * The regular php check done by '==' compares all attributes of
-	 * two objects, which isn't required. The method will first check
-	 * if the objects are instances of the same class.
+	 * two objects, which is often not required. The method will first check
+	 * if the objects are instances of the same class and than if they
+	 * have the same id.
 	 *
 	 * @param object $object1 object to look for (needle)
 	 * @param array $list list of objects (haystack)
@@ -190,6 +193,8 @@ class SeedDMS_Core_DMS {
 	 * Checks if date conforms to a given format
 	 *
 	 * @param string $date date to be checked
+	 * @param string $format format of date. Will default to 'Y-m-d H:i:s' if
+	 * format is not given.
 	 * @return boolean true if date is in propper format, otherwise false
 	 */
 	static function checkDate($date, $format='Y-m-d H:i:s') { /* {{{ */
@@ -198,11 +203,16 @@ class SeedDMS_Core_DMS {
 	} /* }}} */
 
 	/**
-	 * Filter objects out which are not accessible in a given mode by a user.
+	 * Filter out objects which are not accessible in a given mode by a user.
+	 *
+	 * The list of objects to be checked can be of any class, but has to have
+	 * a method getAccessMode($user) which checks if the given user has at
+	 * least access rights to the object as passed in $minMode.
 	 *
 	 * @param array $objArr list of objects (either documents or folders)
 	 * @param object $user user for which access is checked
-	 * @param integer $minMode minimum access mode required
+	 * @param integer $minMode minimum access mode required (M_ANY, M_NONE,
+	 *        M_READ, M_READWRITE, M_ALL)
 	 * @return array filtered list of objects
 	 */
 	static function filterAccess($objArr, $user, $minMode) { /* {{{ */
@@ -218,12 +228,17 @@ class SeedDMS_Core_DMS {
 	} /* }}} */
 
 	/**
-	 * Filter users out which cannot access an object in a given mode.
+	 * Filter out users which cannot access an object in a given mode.
+	 *
+	 * The list of users to be checked can be of any class, but has to have
+	 * a method getAccessMode($user) which checks if a user has at least
+	 * access rights as passed in $minMode.
 	 *
 	 * @param object $obj object that shall be accessed
 	 * @param array $users list of users which are to check for sufficient
 	 *        access rights
 	 * @param integer $minMode minimum access right on the object for each user
+	 *        (M_ANY, M_NONE, M_READ, M_READWRITE, M_ALL)
 	 * @return array filtered list of users
 	 */
 	static function filterUsersByAccess($obj, $users, $minMode) { /* {{{ */
@@ -236,10 +251,11 @@ class SeedDMS_Core_DMS {
 	} /* }}} */
 
 	/**
-	 * Filter document links
+	 * Filter out document links which can not be accessed by a given user
 	 *
 	 * Returns a filtered list of links which are accessible by the
-	 * given user.
+	 * given user. A link is only accessible, if it is publically visible,
+	 * owned by the user, or the accessing user is an administrator.
 	 *
 	 * @param array $links list of objects of type SeedDMS_Core_DocumentLink
 	 * @param object $user user for which access is being checked
@@ -256,7 +272,8 @@ class SeedDMS_Core_DMS {
 	/**
 	 * Create a new instance of the dms
 	 *
-	 * @param object $db object to access the underlying database
+	 * @param object $db object of class {@link SeedDMS_Core_DatabaseAccess}
+	 *        to access the underlying database
 	 * @param string $contentDir path in filesystem containing the data store
 	 *        all document contents is stored
 	 * @return object instance of {@link SeedDMS_Core_DMS}
@@ -394,21 +411,6 @@ class SeedDMS_Core_DMS {
 		$this->viewOnlineFileTypes = $types;
 	} /* }}} */
 
-	/**
-	 * Login as a user
-	 *
-	 * Checks if the given credentials are valid and returns a user object.
-	 * It also sets the property $user for later access on the currently
-	 * logged in user
-	 *
-	 * @param string $username login name of user
-	 * @param string $password password of user
-	 *
-	 * @return object instance of class {@link SeedDMS_Core_User} or false
-	 */
-	function login($username, $password) { /* {{{ */
-	} /* }}} */
-
 	/**
 	 * Set the logged in user
 	 *