Index: DASISH/t5.6/backend/annotator-backend/trunk/annotator-backend/src/main/java/eu/dasish/annotation/backend/dao/AnnotationDao.java
===================================================================
--- DASISH/t5.6/backend/annotator-backend/trunk/annotator-backend/src/main/java/eu/dasish/annotation/backend/dao/AnnotationDao.java	(revision 5892)
+++ DASISH/t5.6/backend/annotator-backend/trunk/annotator-backend/src/main/java/eu/dasish/annotation/backend/dao/AnnotationDao.java	(revision 5989)
@@ -41,38 +41,82 @@
      */
     
+    /**
+     * 
+     * @param headline the headline of an annotation.
+     * @return the list of uuid-s of the annotations with this headline; may be empty.
+     */
     public List<UUID> getExternalIdFromHeadline(String headline);
     
+    /**
+     * 
+     * @param headline the headline of an annotation.
+     * @return the list of internal (database) identifiers of the annotations with this headline; may be empty.
+     */
     public List<Number>  getInternalIDsFromHeadline(String headline);
     /**
      * 
-     * @param annotationID
-     * @return the pair (annotation, owner_id) with empty list of Targets.
-     * 
-     * (Constructing a complete Annotation object using  "getAnnotationWithoutTargets" and "retrieveTargetIDs" is done in "DaoDispatchter".)
-     * 
+     * @param annotationID the internal (database) identifier of an annotation.
+     * @return the {@link Annotation} object whose fields are filled in partially, 
+     * only with the information accessible from the table "annotation". 
+     * Constructing a complete {@link Annotation} object is done in the implementation of {@link DBDispatchter}.)
      */
     public Annotation getAnnotationWithoutTargetsAndPemissionList(Number annotationID);
     
-      
+    /**
+     * 
+     * @param ownerID the owner of annotations we search for; if null then the owner may be any.
+     * @param text the text fragment which must occur in an annotation-body; if null, the now requirements on the annotation body.
+     * @param namespace (search on the parameter is not implemented).
+     * @param after the earliest time of creating/last-update of annotations; if null then search "from the beginning of time".
+     * @param before the latest time of creating/last-update of annotations; if null then search "till now".
+     * @return 
+     */ 
     public List<Number> getFilteredAnnotationIDs(Number ownerID, String text, String namespace, String after, String before);
      
+    /**
+     * 
+     * @param principalID the internal database ID of a principal (user or, in general, a group).
+     * @param acess access level (none, read, write, all).
+     * @return the list of internal (database) annotation identifiers to which "principalID" has access at least "acess".
+     * For instance, on access==write, the method should output id-s of the annotations to which user has "write" (update bodies), 
+     * or "all" access, according to the junction table "annotations-principals-acesses".
+     */
+    public List<Number> getAnnotationIDsPermissionAtLeast(Number principalID, Access acess);
+    
+    /**
+     * 
+     * @param access the value of public assess of an annotation.
+     * @return The list of internal (database identifiers to which public has at least "access" access;
+     * for instance on "write" the method should output annotations 
+     * whose "public" value is "write" or "all".
+     */
+    public List<Number> getAnnotationIDsPublicAtLeast(Access access);
+    
+   
   
-    public List<Number> getAnnotationIDsPermissionAtLeast(Number principalID, Access acess);
-    
-   
-    public List<Number> getAnnotationIDsPublicAtLeast(Access access);
-    
-   
-    /*
-     * Use inly in the debugging mode to acces all the existing annotations.
+    /**
+     * 
+     * @return the list of the internal (database) annotation IDs of all the annotations; 
+     * used only by the developers and the admin in the debugging mode to access all the existing annotations.
      */
     public List<Number> getAllAnnotationIDs();
     
+    /**
+     * 
+     * @param annotationIDs the list of internal annotationIDs.
+     * @param offset the offset parameter for SELECT SQL request.
+     * @param limit the limit parameter for SELECT SQL request.
+     * @param orderedBy criterion of ordering according to the SQL syntax (by some field).
+     * @param desc direction of ordering according to the SQL syntax.
+     * @return the SELECT response on the given parameters: i.e. the list of annotationID's starting from offset and to limit,
+     * if the database rows are ordered according to "orderedBy" and "desc".
+     */
     public List<Number> sublistOrderedAnnotationIDs(List<Number> annotationIDs, int offset, int limit, String orderedBy, String desc);
     
-       /**
-     * unit test is missing
+     /**
      * @param annotationIDs
-     * @return annotationInfo  for the annotation with the internal annotationID.
+     * @return annotationInfo for the annotation with the internal annotationID: 
+     * i.e. the information which you can take only from the "annotation" table
+     * and not the junction tables connecting the annotations to permissions and targets.
      * 
      */
@@ -82,10 +126,15 @@
      * 
      * @param annotationIDs
-     * @return list of reTarget references where an i-th reference is constructed from the external identifier of the annotation with the i-th internal identifier from the list.
+     * @return list of target references where the i-th reference is constructed from the external 
+     * identifier of the annotation with the i-th internal identifier from the list.
      */
     public List<String> getAnnotationREFs(List<Number> annotationIDs); 
     
   
-    
+    /**
+     * 
+     * @param annotationID
+     * @return the internal database ID of the owner of the annotation.
+     */
     public Number  getOwner(Number annotationID);
     
@@ -94,28 +143,39 @@
      * @param annotationID
      * @param principalID
-     * @return access of the principalID w.r.t. annotationID, or null if the access is not given
+     * @return access of the principalID w.r.t. annotationID, or Access.NONE if the access is not given.
      */ 
     public Access  getAccess(Number annotationID, Number principalID);
     
+    /**
+     * 
+     * @param annotationID
+     * @param principalID
+     * @return true if there is triple (annotationID, principalID, access) for some access
+     * in the corresponding junction table; false otherwise.
+     */
     public boolean  hasExplicitAccess(Number annotationID, Number principalID);
     
-    
+    /**
+     * 
+     * @param annotationID
+     * @return the value of the "public" field for annotationID; can be one of ACCESS values.
+     */
     public Access getPublicAttribute(Number annotationID);
     
     
-    
+    /**
+     * 
+     * @param notebookID
+     * @return the list of annotationIDs of the annotations from the notebook with notebookID.
+     */
     public List<Number> getAnnotations(Number notebookID);
     
-    
+    /**
+     * 
+     * @param targetID
+     * @return true if at least one annotation refers to this target; false otherwise.
+     */
     public boolean targetIsInUse(Number targetID);
-    /**
-     * 
-     * @param annotationID
-     * @return true if "annotationID" is mentioned in at least one of the joint tables:
-     * "annotations_targets", "annotations_principals_accesss", "notebook_annotations".
-     * Otherwise return "false".
-     */
-    //public boolean annotationIsInUse(Number annotationID);
-    
+  
     /**
      * ADDERS 
@@ -126,7 +186,7 @@
      * @param annotationID
      * @param targetID
-     * @return # updated rows in the joint table "annotations_target_Targets".
-     * @throws SQLException 
-     * Connects the annotation to its target Target by adding the pair (annotationID, TargetID) to the joint table.
+     * @return # updated rows in the joint table "annotations_targets".
+     * Connects the annotation to its target by adding the pair (annotationID, targetID) 
+     * to the junction table.
      */ 
     public int addAnnotationTarget(Number annotationID, Number targetID);
@@ -138,5 +198,5 @@
      * @param principalID
      * @param access
-     * @return # rows added to the table "annotations_principals_accesss"
+     * @return # rows added to the table "annotations_principals_access".
      * Sets the "access" for the "principalID" w.r.t. the annotation with "annotationID".
      */
@@ -144,11 +204,12 @@
     
     
-  
-     /**
-     * 
-     * @param annotation: the object to be added to the table "annotation".
-     * @return  the internal ID of the added annotation, if it is added, or null otherwise.
-     **/
-    
+ 
+    /**
+     * 
+     * @param annotationthe the object to be added to the table "annotation".
+     * @param newOwnerID the ownerID,
+     * @return the internal ID of the added annotation, if it is added, or throws NotInDataBaseException otherwise.
+     * @throws NotInDataBaseException if the request on the internal database annotation ID for the added annotation throws this exception.
+     */
     public Number addAnnotation(Annotation annotation, Number newOwnerID)  throws NotInDataBaseException;
  
@@ -156,7 +217,20 @@
     /////// UPDATERS //////////////////
     
-   
+   /**
+    * 
+    * @param annotationID the internal database ID of the annotation to be updated.
+    * @param text the new body text.
+    * @param mimeType the new mime type.
+    * @param isXml if the new body is a text body or an xml.
+    * @return # of updated rows in the table "annotation".
+    */
     public int updateAnnotationBody(Number annotationID, String text, String mimeType, Boolean isXml);
     
+    /**
+     * 
+     * @param annotationID the internal database ID of the annotation to be updated.
+     * @param text the new headline.
+     * @return # of updated rows in the table "annotation".
+     */
     public int updateAnnotationHeadline(Number annotationID, String text);
     
@@ -166,6 +240,12 @@
      * 
      * @param annotation
-     * @return # of updated rows in "annotation" table after updating the annotation. Should return 1 if update  happens
-     * @throws SQLException 
+     * @return # of updated rows in "annotation" table after updating the annotation. Should return 1 if update  happens.
+     */
+    /**
+     * 
+     * @param annotation the new annotation (including targets and permissions).
+     * @param annotationID the ID of the annotation to be updated.
+     * @param ownerID the Id of the new owner.
+     * @return # of updated rows in "annotation" table after this FULL updating the annotation. Should return 1 if update  happens.
      */
     public int updateAnnotation(Annotation annotation, Number annotationID, Number ownerID);
@@ -177,10 +257,15 @@
      * @param principalID
      * @param access
-     * @return # rows updated to the table "annotations_principals_accesss"
+     * @return # rows updated to the table "annotations_principals_access".
      * Sets the "access" for the "principalID" w.r.t. the annotation with "annotationID".
      */
     public int updatePermission(Number annotationID, Number principalID, Access access);
     
-    
+    /**
+     * 
+     * @param annotationID the internal database ID of the annotation to be updated.
+     * @param access access level.
+     * @return # of updated rows in "annotation". should be "1" if updated and "0" otherwise.
+     */
     public int updatePublicAccess(Number annotationID, Access access);
     
@@ -212,11 +297,22 @@
     * 
     * @param annotationID
-    * @return # removed rows in the table "annotations_principals_accesss".
-    * @throws SQLException 
+    * @return # removed rows in the table "annotations_principals_access".
     */
     public int deletePermissions(Number annotationID);
     
+    /**
+     * 
+     * @param annotationID
+     * @param principalID
+     * @return # removed rows in the table "annotations_principals_access". 
+     * Should be "1" is removed and "0" otherwise.
+     */
     public int deletePermission(Number annotationID, Number principalID);
     
+    /**
+     * 
+     * @param annotationID
+     * @return # removed rows in the table "notebookds_annotations".
+     */
     public int deleteAnnotationFromAllNotebooks(Number annotationID);
     
@@ -225,4 +321,9 @@
      */
     
+    /**
+     * 
+     * @param annotationBody
+     * @return two string components of the annotationBody: the text/xml content and the mime type.
+     */
     public String[] retrieveBodyComponents(AnnotationBody annotationBody);
 
