Imrpoving documentation

docs/index.rst

@@ -171,6 +171,7 @@ The following collections are available to any users. Non-safe methods can only
 * `Profile Collection <../api-docs/resource_Profile.html>`_;
 * `Namespace Collection <../api-docs/resource_Namespace.html>`_;
 * `License Collection <../api-docs/resource_License.html>`_;
+* `Trash Collection <../api-docs/resource_Trash.html>`_;
 
 The following collections are available only for Catalogue-Admins or above:
 
@@ -185,6 +186,10 @@ An overwiew of the available collections is available at `<../api-docs/index.htm
 Roles
 ------------------
 
+Any user has one or more role in the catalogue.
+Roles can only be assigned by the VRE Manager. 
+ 
+
 The catalogue uses the following hierarchic roles:
 
 Catalogue-Member: 
@@ -216,8 +221,56 @@ Moderated Catalogues
 Any catalogues can be declared as moderated.
 In such a case any submitted items must be approved by a Catalogue-Moderator.
 
-This is the workflow of a item in moderated Catalogue.
- 
+In a moderated catalogue, an item can be in the following states:
+
+pending: 
+	the item published by any allowed users and still not Catalogue-Moderator;
+	
+approved:
+	the item published by any allowed users and rejected by a Catalogue-Moderator;
+	
+rejected:
+	the item published by any allowed users and approved by a Catalogue-Moderator.
+
+
+
+In the following are presented the moderation operations an allowed user can perform to an item. 
+To present the moderation operation the following convenction is used:
+
+	``initial_state``  ---**operation** (*User/Role perfoming the operation*)---> ``final_state``  
+
+
+``initial_state`` can be ``none`` which means that the item does not exists.
+
+
+The following are the allowed moderation operation on a item in a and the 
+
+	``none``  ---**create** (*Author*)---> ``pending``
+	
+
+ 	``pending`` ---**reject** (*Catalogue-Moderator*)---> ``rejected``
+	
+	``pending`` ---**approve** (*Catalogue-Moderator*)---> ``approved``
+	
+	``rejected`` ---**update** (*Author*)---> ``rejected``
+
+	``approved`` ---**update** (*Author*)--->  ``pending``
+
+
+In a moderated catalogue both the Catalogue-Moderators and the item author can send messages to
+discuss about the approval process of the item. The message are related to a specific item.
+A message sent by an Author is received by any Catalogue-Moderators.
+A message sent by a Catalogue-Moderator is received by the author as weel as the other Catalogue-Moderators (if any).
+
+
+Messages can be sent both together with an action which change the status of the item or as explicit action which does not change the status of the item:
+
+	``pending`` ---**message** (*Author OR Catalogue-Moderator*)---> ``pending``
+
+	``rejected`` ---**message** (*Author OR Catalogue-Moderator*)---> ``rejected``
+
+	``approved`` ---**message** (*Author OR Catalogue-Moderator*)---> ``approved``
+
 
 
 

src/main/java/org/gcube/gcat/rest/Item.java

@@ -131,9 +131,9 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 	 * 
 	 * 		It can assume the following values:
 	 * 		<ul>
-	 * 			<li><code>pending</code>: it returns only the pending items, i.e. the item published by any allowed users and still not moderated;</li>
-	 * 			<li><code>rejected</code>: it returns only the rejected items, i.e. the item published by any allowed users and rejected by a moderator;</li>
-	 * 			<li><code>approved</code>: it returns only the approved items, i.e. the item published by any allowed users and approved by a moderated.</li>
+	 * 			<li><code>pending</code>: it returns only the pending items, i.e. the item published by any allowed users and still not <span style="font-weight:bold;">Catalogue-Moderator</span>;</li>
+	 * 			<li><code>rejected</code>: it returns only the rejected items, i.e. the item published by any allowed users and rejected by a <span style="font-weight:bold;">Catalogue-Moderator</span>;</li>
+	 * 			<li><code>approved</code>: it returns only the approved items, i.e. the item published by any allowed users and approved by a <span style="font-weight:bold;">Catalogue-Moderator</span>.</li>
 	 * 		</ul>
 	 * 
 	 * 		<p>