From 627adbf9a46d9a1240738dbed4d836e3a43ac66c Mon Sep 17 00:00:00 2001
From: Johan Vervloet <johanv@johanv.org>
Date: Thu, 18 Jun 2015 11:13:00 +0200
Subject: [PATCH] CRM-16701 - cleanup in phpdoc comments for saved search api.

----------------------------------------
* CRM-16701: Create API for saved searches
  https://issues.civicrm.org/jira/browse/CRM-16701
---
 api/v3/SavedSearch.php | 88 ++++++++++++++++++++----------------------
 1 file changed, 42 insertions(+), 46 deletions(-)

diff --git a/api/v3/SavedSearch.php b/api/v3/SavedSearch.php
index c1f08374ae..d999004370 100644
--- a/api/v3/SavedSearch.php
+++ b/api/v3/SavedSearch.php
@@ -1,28 +1,29 @@
 <?php
+
 /*
- +--------------------------------------------------------------------+
- | CiviCRM version 4.6                                                |
- +--------------------------------------------------------------------+
- | Copyright Chirojeugd-Vlaanderen vzw 2015                           |
- +--------------------------------------------------------------------+
- | This file is a part of CiviCRM.                                    |
- |                                                                    |
- | CiviCRM is free software; you can copy, modify, and distribute it  |
- | under the terms of the GNU Affero General Public License           |
- | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
- |                                                                    |
- | CiviCRM is distributed in the hope that it will be useful, but     |
- | WITHOUT ANY WARRANTY; without even the implied warranty of         |
- | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
- | See the GNU Affero General Public License for more details.        |
- |                                                                    |
- | You should have received a copy of the GNU Affero General Public   |
- | License and the CiviCRM Licensing Exception along                  |
- | with this program; if not, contact CiviCRM LLC                     |
- | at info[AT]civicrm[DOT]org. If you have questions about the        |
- | GNU Affero General Public License or the licensing of CiviCRM,     |
- | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
- +--------------------------------------------------------------------+
+  +--------------------------------------------------------------------+
+  | CiviCRM version 4.6                                                |
+  +--------------------------------------------------------------------+
+  | Copyright Chirojeugd-Vlaanderen vzw 2015                           |
+  +--------------------------------------------------------------------+
+  | This file is a part of CiviCRM.                                    |
+  |                                                                    |
+  | CiviCRM is free software; you can copy, modify, and distribute it  |
+  | under the terms of the GNU Affero General Public License           |
+  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
+  |                                                                    |
+  | CiviCRM is distributed in the hope that it will be useful, but     |
+  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
+  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
+  | See the GNU Affero General Public License for more details.        |
+  |                                                                    |
+  | You should have received a copy of the GNU Affero General Public   |
+  | License and the CiviCRM Licensing Exception along                  |
+  | with this program; if not, contact CiviCRM LLC                     |
+  | at info[AT]civicrm[DOT]org. If you have questions about the        |
+  | GNU Affero General Public License or the licensing of CiviCRM,     |
+  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
+  +--------------------------------------------------------------------+
  */
 
 /**
@@ -32,35 +33,29 @@
  */
 
 /**
- * Create a saved search.
+ * Create or update a saved search.
  *
  * @param array $params
- *
- * @return array
+ *   Associative array of property name-value pairs to insert in new saved search.
+ * @example SavedSearch/Create.php Std create example.
+ * @return array api result array
+ *   {@getfields saved_search_create}
+ * @access public
  */
 function civicrm_api3_saved_search_create($params) {
   return _civicrm_api3_basic_create(_civicrm_api3_get_BAO(__FUNCTION__), $params);
 }
 
 /**
- * Adjust Metadata for Create action.
- *
- * The metadata is used for setting defaults, documentation & validation.
+ * Delete an existing saved search.
  *
  * @param array $params
- *   Array of parameters determined by getfields.
- */
-function _civicrm_api3_saved_search_create_spec(&$params) {
-  // TODO: find out wherther something needs to be done here.
-}
-
-/**
- * Deletes an existing saved search.
- *
- * @param array $params
- *
- * @return array
- *   API result Array
+ *   Associative array of property name-value pairs. $params['id'] should be
+ *   the ID of the saved search to be deleted.
+ * @example SavedSearch/Delete.php Std delete example.
+ * @return array api result array
+ *   {@getfields saved_search_delete}
+ * @access public
  */
 function civicrm_api3_saved_search_delete($params) {
   return _civicrm_api3_basic_delete(_civicrm_api3_get_BAO(__FUNCTION__), $params);
@@ -70,10 +65,11 @@ function civicrm_api3_saved_search_delete($params) {
  * Retrieve one or more saved search(es).
  *
  * @param array $params
- *   An associative array of name/value pairs.
- *
- * @return array
- *   details of found saved searches
+ *   An associative array of name-value pairs.
+ * @example SavedSearch/Get.php Std get example.
+ * @return array api result array
+ *   {@getfields saved_search_get}
+ * @access public
  */
 function civicrm_api3_saved_search_get($params) {
   return _civicrm_api3_basic_get(_civicrm_api3_get_BAO(__FUNCTION__), $params);
-- 
2.25.1