Improve JSON API documentation

UI/Common/UIxAclEditor.m

@@ -83,6 +83,21 @@
   return defaultUserID;
 }
 
+/**
+ * @api {get} /so/:username/:folderPath/acls Get ACLs
+ * @apiVersion 1.0.0
+ * @apiName GetAcls
+ * @apiGroup Common
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Calendar/personal/acls
+ *
+ * @apiSuccess (Success 200) {Object[]} users       List of users with ACL for the folder
+ * @apiSuccess (Success 200) {String} uid           User ID
+ * @apiSuccess (Success 200) {String} userClass     Either 'normal-user', 'normal-group' or 'public-access'
+ * @apiSuccess (Success 200) {Number} isSubscribed  1 if the user is subscribed to the folder
+ * @apiSuccess (Success 200) {String} [cn]          User fullname
+ * @apiSuccess (Success 200) {String} [c_email]     User main email address
+ */
 - (id <WOActionResults>) aclsAction
 {
   id <WOActionResults> result;
@@ -145,7 +160,7 @@
     }
 
   result = [self responseWithStatus: 200
-                          andString: [users jsonRepresentation]];
+              andJSONRepresentation: [NSDictionary dictionaryWithObject: users forKey: @"users"]];
 
   return result;
 }

UI/Common/UIxFolderActions.m

@@ -205,6 +205,18 @@
   return [self _realFolderActivation: NO];
 }
 
+/**
+ * @api {get} /so/:username/:folderPath/newguid Generate new ID
+ * @apiVersion 1.0.0
+ * @apiName GetNewGUID
+ * @apiGroup Common
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Calendar/personal/newguid
+ *
+ * @apiSuccess (Success 200) {String} pid Folder ID (element's parent)
+ * @apiSuccess (Success 200) {String} id  New element ID
+ * @apiError   (Error 500) {Object} error The error message
+ */
 - (WOResponse *) newguidAction
 {
   NSString *objectId, *folderId;
@@ -413,13 +425,24 @@
   return response;
 }
 
+/**
+ * @api {get} /so/:username/:folderPath/subscribeUsers?uids=:uids Subscribe user(s)
+ * @apiVersion 1.0.0
+ * @apiName GetSubscribeUsers
+ * @apiGroup Common
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Calendar/personal/subscribeUsers?uids=sogo2,sogo3
+ *
+ * @apiParam {String} uids Comma-separated list of user IDs
+ *
+ * @apiError (Error 400) {Object} error The error message
+ */
 - (id <WOActionResults>) subscribeUsersAction
 {
   id <WOActionResults> response;
   NSString *uids;
   NSArray *userIDs;
   SOGoGCSFolder *folder;
-  NSException *ex;
   int count, max;
   
   uids = [[context request] formValueForKey: @"uids"];
@@ -432,16 +455,12 @@
         [folder subscribeUserOrGroup: [userIDs objectAtIndex: count]
 			    reallyDo: YES
                             response: nil];
-      ex = nil;
+      response = [self responseWith204];
     }
   else
-    ex = [NSException exceptionWithHTTPStatus: 400
-                                       reason: @"missing 'uids' parameter"];
-  
-  if (ex)
-    response = (id <WOActionResults>) ex;
-  else
-    response = [self responseWith204];
+    response = [self responseWithStatus: 400
+                  andJSONRepresentation: [NSDictionary dictionaryWithObject: @"missing 'uids' parameter"
+                                                                     forKey: @"error"]];
   
   return response;
 }

UI/Common/UIxObjectActions.m

@@ -39,6 +39,16 @@
 
 @implementation UIxObjectActions
 
+/**
+ * @api {get} /so/:username/:folderPath/addUserInAcls?uid=:uid Add user to ACLs
+ * @apiVersion 1.0.0
+ * @apiName GetAddUserInAcls
+ * @apiGroup Common
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Calendar/personal/addUserInAcls?uid=sogo2
+ *
+ * @apiParam {String} uid User ID
+ */
 - (WOResponse *) addUserInAclsAction
 {
   WOResponse *response;
@@ -57,6 +67,16 @@
   return response;
 }
 
+/**
+ * @api {get} /so/:username/:folderPath/removeUserFromAcls?uid=:uid Remove user from ACLs
+ * @apiVersion 1.0.0
+ * @apiName GetRemoveUserFromAcls
+ * @apiGroup Common
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Calendar/personal/removeUserInAcls?uid=sogo2
+ *
+ * @apiParam {String} uid User ID
+ */
 - (WOResponse *) removeUserFromAclsAction
 {
   WOResponse *response;