Improving documentation

docs/index.rst

@@ -29,7 +29,10 @@ You can call the methods of the Web Service by writing your own REST client appl
 HTTP Statuses
 ------------------
 
-Any successful operation returns *200 OK* status code. The create operation returns *201 Created*. Instead, the operations do not provide any content return *204 No Content*.
+Any successful operation returns *200 OK* HTTP status code. 
+The create operation returns *201 Created*. 
+Instead, the operations do not provide any content return *204 No Content*.
+A Background operation returns *202 Accepted*.
 
 The most common error status a client can obtain are:
 

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

@@ -170,10 +170,10 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 	 * </p> 
 	 * 
 	 * 
-	 * @param limit To get unlimited results the limit query parameters must be set to -1. 
+	 * @param limit (<em>Default:10</em>) To get unlimited results the limit query parameters must be set to -1. 
 	 * 	If the results are too much the operation could fail. 
 	 * 	It is recommended to request no more than 1000 results. 
-	 * @param offset The offset parameter indicates the starting position of the result.
+	 * @param offset <em>Default:0</em>) The offset parameter indicates the starting position of the result.
 	 * @return It returns an array list of string containing the ids (i.e. names) of the items.
 	 * 	E.g.<pre>["item0","items1",...,"item10"]</pre>
 	 * 	
@@ -306,6 +306,40 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 		thread.start();
 	}
 	
+	/**
+	 * The bulk delete API provides a way to delete all the times matching certain criteria 
+	 * (see Filtering Listing options).
+	 * The operation returns immediately to the client and continues in background.
+	 * There is no way to monitor or stop the running operation.
+	 * 
+	 * When invoked with no arguments, it deletes all the items of the invoking user in the default 
+	 * CKAN organization for the current context.
+	 * 
+	 * If a Catalogue-Admins or above specifies the query parameter <em>own_only=false</em> 
+	 * it deletes all the items of all users for the CKAN organization for the current context. 
+	 * The service ignores the query parameter <em>own_only=false</em> if the requesting user is not 
+	 * Catalogue-Admins or above.
+	 * 
+	 * <p style="font-weight:bold;">
+	 * 	Please check the result using the items listing APIs to verify what you will delete.
+	 * </p>
+	 * 
+	 * <p>
+	 * 	The deleted items are moved to the thrash by default.
+	 * 	To completely remove the items (i.e. purge) the user can use the query parameter <em>purge=true</em>.
+	 * 	<span style="font-weight:bold;">Please note that the purge action is not reversible.</span>
+	 * </p>
+	 * 
+	 * <p>
+	 * 	By indicating the query parameter <em>purge=true</em> has the same result of using the bulk 
+	 * 	purge API using the <code>PURGE</code> HTTP Method.
+	 * </p>
+	 * 
+	 * @param purge <em>Default:false</em>) it completely removes all the items in the default CKAN organization.
+	 * @return <code>202 Accepted</code> HTTP Status to indicate that the request has been properly take in charge.
+	 * 	The operation will continue in background.
+	 * @throws WebServiceException if an error occurs.
+	 */
 	@DELETE
 	@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
 	@Override
@@ -315,6 +349,33 @@ public class Item extends REST<CKANPackage> implements org.gcube.gcat.api.interf
 		return Response.status(Status.ACCEPTED).build();
 	}
 	
+	/**
+	 * The bulk purge API provides a way to completely remove all the times matching certain criteria 
+	 * (see Filtering Listing options). Please note that this action is not reversible.
+	 * The operation returns immediately to the client and continues in background.
+	 * There is no way to monitor or stop the running operation.
+	 * 
+	 * When invoked with no arguments, it purges all the items of the invoking user in the default 
+	 * CKAN organization for the current context.
+	 * 
+	 * If a Catalogue-Admins or above specifies the query parameter <em>own_only=false</em>,
+	 * it purges all the items of all users for the CKAN organization for the current context. 
+	 * The service ignores the query parameter <em>own_only=false</em> if the requesting user is not 
+	 * Catalogue-Admins or above.
+	 * 
+	 * <p style="font-weight:bold;">
+	 * 	Please check the result using the items listing APIs to verify what you will purge.
+	 * </p>
+	 * 
+	 * <p>
+	 * 	Invoking this API has the same result of using the bulk delete API using the <code>DELETE</code> HTTP Method
+	 *  with the query parameters <em>purge=true</em>.
+	 * </p>
+	 * 
+	 * @return <code>202 Accepted</code> HTTP Status to indicate that the request has been properly take in charge.
+	 * 	The operation will continue in background.
+	 * @throws WebServiceException if an error occurs.
+	 */
 	@PURGE
 	@Produces(GCatConstants.APPLICATION_JSON_CHARSET_UTF_8)
 	@Override