From 828e72ad02216bd8ba218551fad150110da42cfe Mon Sep 17 00:00:00 2001
From: Gilles Crettenand <gilles@crettenand.info>
Date: Wed, 3 Jun 2015 09:14:32 +0200
Subject: [PATCH] more phpdoc

---
 NetBiblio.php | 43 +++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 41 insertions(+), 2 deletions(-)

diff --git a/NetBiblio.php b/NetBiblio.php
index 3004e75..73d92ce 100644
--- a/NetBiblio.php
+++ b/NetBiblio.php
@@ -393,6 +393,13 @@ class NetBiblio extends WebService
         return reset($this->AddBookData(BookSearch::GetBooks(array($code))));
     }
 
+    /**
+     * This method returns
+     * @param int $number
+     * @param null $seed
+     * @return array
+     * @throws WebException
+     */
     public function GetRandomBooks($number = 100, $seed = null) {
         if(is_null($seed)) {
             $seed = time();
@@ -404,6 +411,17 @@ class NetBiblio extends WebService
         return $this->AddBookData($results['books']);
     }
 
+    /**
+     * This method is used by the iOS application to perform searching.
+     * If a number is given, search in the book codes, otherwise perform
+     * a full text search.
+     *
+     * @param string $query Text to search
+     * @param int $start
+     * @param int $limit
+     * @return array
+     * @throws WebException
+     */
     public function Search($query, $start, $limit)
     {
         $query = array(
@@ -420,6 +438,16 @@ class NetBiblio extends WebService
         return $data;
     }
 
+    /**
+     * This method is used by the website and the Android application to perform
+     * book search.
+     *
+     * TODO: describe various options for the parameters
+     *
+     * @param string $values JSON encoded object
+     * @return array
+     * @throws WebException
+     */
     public function NewSearch($values)
     {
         $this->CheckSession();
@@ -492,6 +520,11 @@ class NetBiblio extends WebService
         return array_merge($data, $this->AddBookData($results['books']));
     }
 
+    /**
+     * This method returns the list of all volunteer readers that read book
+     * in the database.
+     * @return array
+     */
     public function ListOfReaders()
     {
         return AudioBook::listOfReaders();
@@ -529,6 +562,12 @@ class NetBiblio extends WebService
         }, AudioBook::ListOfGenres(true));
     }
 
+    /**
+     * This method returns the list of all books that are currently
+     * being read by the volunteers.
+     *
+     * @return array
+     */
     public function InReadingBooks()
     {
         return AudioBook::inReading();
@@ -539,8 +578,8 @@ class NetBiblio extends WebService
      * books for a given Genre. It may receives the genre 'Jeunesse' which
      * is a boolean value on Solr documents.
      *
-     * @param $genre
-     * @param $number
+     * @param string $genre Genre for which we want books (not the code)
+     * @param int $number number of books
      * @return array
      * @throws WebException
      */