finish documentation NetBiblio methods

Lib/WebService.php

@@ -13,7 +13,10 @@ abstract class WebService
     private $log = '';
 
     /**
-     * @param $message
+     * Log a message that will be displayed in the logs if the configuration
+     * says so.
+     *
+     * @param string $message
      * @param int $verbosity
      * @param bool $withTime
      */
@@ -29,6 +32,10 @@ abstract class WebService
         $this->log .= $message."\n";
     }
 
+    /**
+     * Treat the current request and output the result. This is the only
+     * method that should be called on the webservice directly !
+     */
     public function Run()
     {
         $renderer = new Renderer();
@@ -67,6 +74,13 @@ abstract class WebService
         }
     }
 
+    /**
+     * Determines which method to call based on GET or POST parameters and
+     * call it before returning the result.
+     *
+     * @return array
+     * @throws UsageException
+     */
     private function Call()
     {
         session_save_path(Configuration::get('session.save_path'));

NetBiblio.php

@@ -232,6 +232,17 @@ class NetBiblio extends WebService
     // *        Public methods          *
     // **********************************
 
+    /**
+     * This method register a download made through the website or mobile application
+     * as a lent and returned book (OldCirculation).
+     *
+     * @param string $client
+     * @param string $login
+     * @param int $code
+     * @return array
+     * @throws Lib\Exception\SqlException
+     * @throws WebException
+     */
     public function AddDownloadLog($client, $login, $code)
     {
         $client = str_replace("'", "", $client);
@@ -310,10 +321,20 @@ class NetBiblio extends WebService
                     2, $worker_id, 2, $worker_id,
                     0, 0, 1, '-', 1, 1
                 );";
-        Connection::execute($sql);
+        $status = Connection::execute($sql);
-        return array('success' => true);
+        return array('success' => $status && ! $status->is_error() && $status->get_num_rows() > 0);
     }
 
+    /**
+     * This method authenticates and store the login information into the session so
+     * that the next calls can be made for this user.
+     *
+     * @param $login
+     * @param $password
+     * @param string $client
+     * @return array
+     * @throws AuthenticationException
+     */
     public function Authenticate($login, $password, $client = "website")
     {
         session_unset(); /* destroy all session vars */
@@ -333,6 +354,11 @@ class NetBiblio extends WebService
         return $user->toArray();
     }
 
+    /**
+     * This method disconnects the current user and clear all session data.
+     *
+     * @return array
+     */
     public function Disconnect()
     {
         $_SESSION = array();
@@ -347,52 +373,115 @@ class NetBiblio extends WebService
         return array('success' => true);
     }
 
+    /**
+     * Return the information associated with the currently authenticated user
+     * if any.
+     *
+     * @return array
+     * @throws AuthenticationException
+     */
     public function IsAuthenticated()
     {
         return $this->getUser()->toArray();
     }
 
+    /**
+     * This method returns the account information for the given login, but only
+     * if it matches the currently authenticated user.
+     *
+     * @param string $login
+     * @return array
+     * @throws AuthenticationException
+     */
     public function FindAccount($login)
     {
         return $this->getUser($login)->toArray();
     }
 
+    /**
+     * This method returns the books on the currently authenticated user wishlist.
+     *
+     * @return array
+     * @throws AuthenticationException
+     */
     public function GetWishes()
     {
         $books = $this->getUser()->getWishes();
         return array_values($this->AddBookData($books));
     }
 
+    /**
+     * This method returns the list of books that are currently let to the
+     * authenticated user.
+     *
+     * @return array
+     * @throws AuthenticationException
+     */
     public function GetCirculations()
     {
         $circulations = $this->getUser()->getCirculations();
         return array_values($this->AddBookData($circulations));
     }
 
+    /**
+     * This method returns the list of books that the currently authenticated user
+     * has downloaded or that were lent to him.
+     *
+     * @return array
+     * @throws AuthenticationException
+     */
     public function GetOldCirculations()
     {
         $circulations = $this->getUser()->getOldCirculations();
         return array_values($this->AddBookData($circulations));
     }
 
-    public function AddWish($bookNr)
+    /**
+     * This method adds a book to the currently authenticated user wishlist
+     * based on its code.
+     *
+     * @param int $code
+     * @return array
+     * @throws AuthenticationException
+     */
+    public function AddWish($code)
     {
-        $status = $this->getUser()->addWish($bookNr);
+        $status = $this->getUser()->addWish($code);
         return array('success' => $status);
     }
 
-    public function DeleteWish($bookNr)
+    /**
+     * This method deletes the given book from the currently authenticated
+     * user wishlist based on its code.
+     *
+     * @param int $code
+     * @return array
+     * @throws AuthenticationException
+     */
+    public function DeleteWish($code)
     {
-        $status = $this->getUser()->deleteWish($bookNr);
+        $status = $this->getUser()->deleteWish($code);
         return array('success' => $status);
     }
 
+    /**
+     * This method returns an array of books based on their code
+     *
+     * @param array|int[] $codes
+     * @return array
+     */
     public function FindBooks($codes)
     {
         $this->CheckSession();
         return array_values($this->AddBookData(BookSearch::GetBooks(json_decode($codes))));
     }
 
+    /**
+     * This method return a book based on its code
+     *
+     * @param int $code
+     * @return array
+     */
     public function FindBook($code)
     {
         $this->CheckSession();
@@ -400,8 +489,11 @@ class NetBiblio extends WebService
     }
 
     /**
-     * This method returns
+     * This method returns a list of random books.
-     * @param int $number
+     * For a given seed, the list should be always the same at least while
+     * Solr is not restarted (or documents re-indexed)
+     *
+     * @param int $number Number of random books to return
      * @param null $seed
      * @return array
      * @throws WebException