From 37e91733ca4c11d5e5a1d4f44605018c21592601 Mon Sep 17 00:00:00 2001
From: Francis Lachapelle <flachapelle@inverse.ca>
Date: Thu, 22 Jan 2015 09:15:44 -0500
Subject: [PATCH] Improve API documentation

---
 UI/Common/UIxFolderActions.m   |  8 +++++++
 UI/Contacts/UIxContactEditor.m | 40 ++++++++++++++++++++++++++++++++++
 UI/Contacts/UIxContactView.m   | 39 +++++++++++++++++++++++++++++++++
 3 files changed, 87 insertions(+)

diff --git a/UI/Common/UIxFolderActions.m b/UI/Common/UIxFolderActions.m
index b048962a6..a71c4e5b1 100644
--- a/UI/Common/UIxFolderActions.m
+++ b/UI/Common/UIxFolderActions.m
@@ -137,6 +137,14 @@
   return [self _subscribeAction: NO];
 }
 
+/**
+ * @api {get} /so/:username/:folderPath/canAccessContent Test access rights
+ * @apiVersion 1.0.0
+ * @apiName GetCanAccessContent
+ * @apiGroup Common
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Calendar/personal/canAccessContent
+ */
 - (WOResponse *) canAccessContentAction
 {
   /* We want this action to be authorized managed by the SOPE's internal acl
diff --git a/UI/Contacts/UIxContactEditor.m b/UI/Contacts/UIxContactEditor.m
index 04159d396..073ec1492 100644
--- a/UI/Contacts/UIxContactEditor.m
+++ b/UI/Contacts/UIxContactEditor.m
@@ -498,6 +498,46 @@ static Class SOGoContactGCSEntryK = Nil;
   [card cleanupEmptyChildren];
 }
 
+
+/**
+ * @api {post} /so/:username/Contacts/:addressbookId/:cardId/save Save card
+ * @apiVersion 1.0.0
+ * @apiName PostData
+ * @apiGroup Contacts
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Contacts/personal/1BC8-52F53F80-1-38C52040.vcf/view
+ *
+ * @apiSuccess (Success 200) {String} id                   Card ID
+ * @apiSuccess (Success 200) {String} pid                  Address book ID (card's container)
+ * @apiSuccess (Success 200) {String} tag                  Either vcard or vlist
+ * @apiSuccess (Success 200) {String} givenname            Firstname
+ * @apiSuccess (Success 200) {String} nickname             Nickname
+ * @apiSuccess (Success 200) {String} sn                   Lastname
+ * @apiSuccess (Success 200) {String} fn                   Fullname
+ * @apiSuccess (Success 200) {String} tz                   Timezone
+ * @apiSuccess (Success 200) {String} note                 Note
+ * @apiSuccess (Success 200) {String[]} allCategories      All available categories
+ * @apiSuccess (Success 200) {Object[]} categories         Categories assigned to the card
+ * @apiSuccess (Success 200) {String} categories.value     Category name
+ * @apiSuccess (Success 200) {Object[]} addresses          Postal addresses
+ * @apiSuccess (Success 200) {String} addresses.type       Type (e.g., home or work)
+ * @apiSuccess (Success 200) {String} addresses.postoffice Post office box
+ * @apiSuccess (Success 200) {String} addresses.street     Street address
+ * @apiSuccess (Success 200) {String} addresses.street2    Extended address (e.g., apartment or suite number)
+ * @apiSuccess (Success 200) {String} addresses.locality   Locality (e.g., city)
+ * @apiSuccess (Success 200) {String} addresses.region     Region (e.g., state or province)
+ * @apiSuccess (Success 200) {String} addresses.postalcode Postal code
+ * @apiSuccess (Success 200) {String} addresses.country    Country name
+ * @apiSuccess (Success 200) {Object[]} emails             Email addresses
+ * @apiSuccess (Success 200) {String} emails.type          Type (e.g., home or work)
+ * @apiSuccess (Success 200) {String} emails.value         Email address
+ * @apiSuccess (Success 200) {Object[]} phones             Phone numbers
+ * @apiSuccess (Success 200) {String} phones.type          Type (e.g., mobile or work)
+ * @apiSuccess (Success 200) {String} phones.value         Phone number
+ * @apiSuccess (Success 200) {Object[]} urls               URLs
+ * @apiSuccess (Success 200) {String} urls.type            Type (e.g., personal or work)
+ * @apiSuccess (Success 200) {String} urls.value           URL
+ */
 - (id <WOActionResults>) saveAction
 {
   SOGoContentObject <SOGoContactObject> *co;
diff --git a/UI/Contacts/UIxContactView.m b/UI/Contacts/UIxContactView.m
index 0e8bb417b..393ce9259 100644
--- a/UI/Contacts/UIxContactView.m
+++ b/UI/Contacts/UIxContactView.m
@@ -737,6 +737,45 @@
   return self;
 }
 
+/**
+ * @api {get} /so/:username/Contacts/:addressbookId/:cardId/view Get card
+ * @apiVersion 1.0.0
+ * @apiName GetData
+ * @apiGroup Contacts
+ * @apiExample {curl} Example usage:
+ *     curl -i http://localhost/SOGo/so/sogo1/Contacts/personal/1BC8-52F53F80-1-38C52040.vcf/view
+ *
+ * @apiSuccess (Success 200) {String} id                   Card ID
+ * @apiSuccess (Success 200) {String} pid                  Address book ID (card's container)
+ * @apiSuccess (Success 200) {String} tag                  Either vcard or vlist
+ * @apiSuccess (Success 200) {String} [givenname]          Firstname
+ * @apiSuccess (Success 200) {String} [nickname]           Nickname
+ * @apiSuccess (Success 200) {String} [sn]                 Lastname
+ * @apiSuccess (Success 200) {String} [fn]                 Fullname
+ * @apiSuccess (Success 200) {String} [tz]                 Timezone
+ * @apiSuccess (Success 200) {String} [note]               Note
+ * @apiSuccess (Success 200) {String[]} allCategories      All available categories
+ * @apiSuccess (Success 200) {Object[]} [categories]       Categories assigned to the card
+ * @apiSuccess (Success 200) {String} categories.value     Category name
+ * @apiSuccess (Success 200) {Object[]} [addresses]        Postal addresses
+ * @apiSuccess (Success 200) {String} addresses.type       Type (e.g., home or work)
+ * @apiSuccess (Success 200) {String} addresses.postoffice Post office box
+ * @apiSuccess (Success 200) {String} addresses.street     Street address
+ * @apiSuccess (Success 200) {String} addresses.street2    Extended address (e.g., apartment or suite number)
+ * @apiSuccess (Success 200) {String} addresses.locality   Locality (e.g., city)
+ * @apiSuccess (Success 200) {String} addresses.region     Region (e.g., state or province)
+ * @apiSuccess (Success 200) {String} addresses.postalcode Postal code
+ * @apiSuccess (Success 200) {String} addresses.country    Country name
+ * @apiSuccess (Success 200) {Object[]} [emails]           Email addresses
+ * @apiSuccess (Success 200) {String} emails.type          Type (e.g., home or work)
+ * @apiSuccess (Success 200) {String} emails.value         Email address
+ * @apiSuccess (Success 200) {Object[]} [phones]           Phone numbers
+ * @apiSuccess (Success 200) {String} phones.type          Type (e.g., mobile or work)
+ * @apiSuccess (Success 200) {String} phones.value         Phone number
+ * @apiSuccess (Success 200) {Object[]} [urls]             URLs
+ * @apiSuccess (Success 200) {String} urls.type            Type (e.g., personal or work)
+ * @apiSuccess (Success 200) {String} urls.value           URL
+ */
 - (id <WOActionResults>) dataAction
 {
   id <WOActionResults> result;