From d3916e6e5e6c26a07190df34e8049a0460b845b5 Mon Sep 17 00:00:00 2001
From: Francis Lachapelle <flachapelle@inverse.ca>
Date: Wed, 29 Apr 2015 22:56:04 -0400
Subject: [PATCH] Improve API documentation

---
 UI/Common/UIxParentFolderActions.m | 17 ++++++++++++++++-
 UI/Scheduler/UIxCalFolderActions.m | 28 ++++++++++++++++++++++------
 UI/Scheduler/UIxCalMainActions.m   | 18 +++++++++++++++++-
 3 files changed, 55 insertions(+), 8 deletions(-)

diff --git a/UI/Common/UIxParentFolderActions.m b/UI/Common/UIxParentFolderActions.m
index 24c0e26af..08e79d161 100644
--- a/UI/Common/UIxParentFolderActions.m
+++ b/UI/Common/UIxParentFolderActions.m
@@ -1,6 +1,6 @@
 /* UIxParentFolderActions.m - this file is part of SOGo
  *
- * Copyright (C) 2007-2014 Inverse inc.
+ * Copyright (C) 2007-2015 Inverse inc.
  *
  * This file is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -36,6 +36,21 @@
 
 @implementation UIxParentFolderActions
 
+/**
+ * @api {post} /so/:username/:module/createFolder Create folder
+ * @apiVersion 1.0.0
+ * @apiName PostCreateFolder
+ * @apiGroup Common
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Calendar/createFolder \
+ *          -H "Content-Type: application/json" \
+ *          -d '{ "name": "Business" }'
+ *
+ * @apiDescription Called to create a new calendar or a new address book.
+ *
+ * @apiParam {String} name            The display name of the new folder
+ * @apiSuccess (Success 201) {String} id Folder ID
+ */
 - (id <WOActionResults>) createFolderAction
 {
   WOResponse *response;
diff --git a/UI/Scheduler/UIxCalFolderActions.m b/UI/Scheduler/UIxCalFolderActions.m
index 0a676472f..f108961bd 100644
--- a/UI/Scheduler/UIxCalFolderActions.m
+++ b/UI/Scheduler/UIxCalFolderActions.m
@@ -1,5 +1,5 @@
 /*
-  Copyright (C) 2006-2013 Inverse inc.
+  Copyright (C) 2006-2015 Inverse inc.
   Copyright (C) 2004-2005 SKYRIX Software AG
 
   This file is part of SOGo
@@ -108,17 +108,33 @@
 }
 
 /* These methods are only available on instance of SOGoWebAppointmentFolder. */
+
+/**
+ * @api {get} /so/:username/Scheduler/:calendarId/reload Load Web calendar
+ * @apiVersion 1.0.0
+ * @apiName PostReloadWebCalendar
+ * @apiGroup Calendar
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Calendar/5B30-55419180-7-6B687280/reload
+ *
+ * @apiDescription Load and parse the events from a remote Web calendar (.ics)
+ *
+ * @apiSuccess (Success 200) {Number} status     The HTTP code received when accessing the remote URL
+ * @apiSuccess (Success 200) {String} [imported] The number of imported events in case of success
+ * @apiError   (Error 500)   {String} [error]    The error type in case of a failure
+ */
 - (WOResponse *) reloadAction
 {
-  WOResponse *response;
   NSDictionary *results;
+  unsigned int httpCode;
 
-  response = [self responseWithStatus: 200];
-  [response setHeader: @"application/json" forKey: @"content-type"];
+  httpCode = 200;
   results = [[self clientObject] loadWebCalendar];
-  [response appendContentString: [results jsonRepresentation]];
 
-  return response;
+  if ([results objectForKey: @"error"])
+    httpCode = 500;
+
+  return [self responseWithStatus: httpCode andJSONRepresentation: results];
 }
 
 - (WOResponse *) setCredentialsAction
diff --git a/UI/Scheduler/UIxCalMainActions.m b/UI/Scheduler/UIxCalMainActions.m
index 947d85e22..7e659ba78 100644
--- a/UI/Scheduler/UIxCalMainActions.m
+++ b/UI/Scheduler/UIxCalMainActions.m
@@ -38,6 +38,22 @@
 
 @implementation UIxCalMainActions
 
+/**
+ * @api {post} /so/:username/Scheduler/addWebCalendar Add Web calendar
+ * @apiVersion 1.0.0
+ * @apiName PostAddWebCalendar
+ * @apiGroup Calendar
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Calendar/addWebCalendar \
+ *          -H "Content-Type: application/json" \
+ *          -d '{ "url": "http://localhost/test.ics" }'
+ *
+ * @apiDescription Called to subscribe to a remote Web calendar (.ics)
+ *
+ * @apiParam {String} url            The URL of the remote Web calendar
+ * @apiSuccess (Success 200) {String} id   Calendar ID
+ * @apiSuccess (Success 200) {String} name The display name of the calendar
+ */
 - (WOResponse *) addWebCalendarAction
 {
   NSDictionary *params;
@@ -64,7 +80,7 @@
         {
           jsonResponse = [NSMutableDictionary dictionary];
           [jsonResponse setObject: [folder displayName] forKey: @"name"];
-          [jsonResponse setObject: [folder name] forKey: @"id"];
+          [jsonResponse setObject: [folder nameInContainer] forKey: @"id"];
         }
       else
         ex = [NSException exceptionWithName: @"newWebCalendarWithURLException"