--- a/Entity/DocumentRepository.php	Fri Nov 18 17:54:30 2011 +0100
+++ b/Entity/DocumentRepository.php	Fri Nov 25 18:55:42 2011 +0100
@@ -2,12 +2,15 @@
 
 namespace IRI\Bundle\WikiTagBundle\Entity;
 
+use IRI\Bundle\WikiTagBundle\Model\DocumentInterface;
+
 use Doctrine\ORM\EntityRepository;
 use IRI\Bundle\WikiTagBundle\Entity\Document;
 use Doctrine\ORM\Query\ResultSetMapping;
 use \ReflectionClass;
 use Doctrine\ORM\AbstractQuery;
 use Doctrine\ORM\Mapping\ClassMetadataInfo;
+use IRI\Bundle\WikiTagBundle\Model\ModelException;
 
 /**
  * DocumentRepository
@@ -18,20 +21,29 @@
 class DocumentRepository extends EntityRepository
 {
     /**
-     *
-     * TODO : Enter description here ...
+     * The cache for the host document class
      * @var ReflectionClass
      */
     private $reflection_class;
+    
+    /**
+     * The cache for the wikitag document class
+     * @var ReflectionClass
+     */
     private $reflection_doc_class;
     private $set_methods = array();
     private $get_methods = array();
-    
-    function findOneByExternalId($external_id)
+
+    /**
+     * Find one wikitagRepository by its externalId i.e. the host document id.
+     * @param $external_id
+     */
+    public function findOneByExternalId($external_id)
     {
         return $this->findOneBy(array("externalId" => $external_id));
     }
     
+    
     private function reflectionSetField($object, $method_name, $value)
     {
         if(isset($this->set_methods[$method_name]))
@@ -126,14 +138,12 @@
                 }
                 else
                 {
-                    //TODO : custom exception
-                    throw new \Exception("Bad reflection object type");
+                    throw new ModelException("Bad reflection object type");
                 }
             }
         }
         
-        //TODO: replace by custom exception
-        throw new \Exception("Unknown accessor $accessor");
+        throw new ModelException("Unknown accessor $accessor");
     }
     
     
@@ -161,6 +171,13 @@
         return $res;
     }
     
+    /**
+     * Write a wikitag document given the host document and the field list.
+     * @param $document The source document
+     * @param $document_id_column the name of the source document id column
+     * @param $fields The list of field definition. This is an associative array [<field name>=><field definition>].
+     *     See the @IRI\Bundle\WikiTagBundle\DependencyInjection\Configuration documentation
+     */
     public function writeDocument($document,  $document_id_column, $fields)
     {
         // get document from id
@@ -202,7 +219,12 @@
     
     }
     
-    function removeDocument($document, $document_id_column)
+    /**
+     * Remove a Wikitag doument given the host docuument.
+     * @param $document The host document
+     * @param string $document_id_column The host document id column name
+     */
+    public function removeDocument($document, $document_id_column)
     {
         $docid = $this->reflectionGetField($document, $document_id_column);
         $baseDocument = $this->findOneByExternalId($docid);
@@ -212,7 +234,13 @@
         }
     }
     
-    function getTagsStr($document)
+    
+    /**
+     * return the list of a wikitag documents the tags label.
+     * @param DocumentInterface $document the wikitag document
+     * @return array
+     */
+    public function getTagsStr($document)
     {
         $em = $this->getEntityManager();
         $query = $em->createQuery("SELECT t.label FROM WikiTagBundle:DocumentTag dt JOIN dt.tag t WHERE dt.document = :docid");
@@ -225,7 +253,11 @@
         return $tagstr;
     }
     
-    function updateTagsStr($document)
+    /**
+     * Update a wikitag document tags string.
+     * @param DocumentInterface $document the wikitag document
+     */
+    function updateTagsStr(DocumentInterface $document)
     {
         
         $tagstr = $this->getTagsStr($document);
@@ -236,11 +268,11 @@
     
 
     /**
+     * Search wikitag documents using the index.
      *
-     * Enter description here ...
      * @param array $values : key: the fields to search into, value : array('value'=>value, 'weight'=>weight)
      * @param array $conditions : array : key : field name, value : simple value (operator is "=") or array(valuea, value2,...) (operatr is IN) or array("operator"=>"", "value"=>value)
-     * @return Ambigous <multitype:, \Doctrine\ORM\mixed, \Doctrine\DBAL\Driver\Statement, \Doctrine\ORM\Internal\Hydration\mixed>
+     * @return array [["id" => <the wikitag document id>, "externalId" => <the host document ids>, "score" => <the score for this document>]]
      */
     function search(array $values, array $conditions=NULL)
     {
@@ -332,8 +364,6 @@
         $res = $query->getResult();
         
         return $res;
-        
-        
     }
         
 }
\ No newline at end of file