X-Git-Url: https://vcs.fsf.org/?a=blobdiff_plain;ds=sidebyside;f=api%2Fv3%2FFile.php;h=b250075fd74b082d278264a4042015c417b30cea;hb=0b2bdd13e190523e68f8ee762b825eaa0a801e4b;hp=f99dd393593d165abfed49a0eb87c9d5c30099bf;hpb=1a4d747351c5963b20ad798f3bd0480eb772b13b;p=civicrm-core.git

diff --git a/api/v3/File.php b/api/v3/File.php
index f99dd39359..b250075fd7 100644
--- a/api/v3/File.php
+++ b/api/v3/File.php
@@ -26,26 +26,22 @@
  */
 
 /**
+ * This api is a simple wrapper of the CiviCRM file DAO.
  *
- * Definition of the Tag of the CRM API.
- * More detailed documentation can be found
- * {@link http://objectledge.org/confluence/display/CRM/CRM+v1.0+Public+APIs
- * here}
+ * Creating and updating files is a complex process and this api is usually insufficient.
+ * Use the "Attachment" api instead for more robust file handling.
  *
+ * @fixme no unit tests
  * @package CiviCRM_APIv3
- * @subpackage API_File
- * @copyright CiviCRM LLC (c) 2004-2014
- * $Id: $
- *
  */
 
 /**
- * Create a file
- *
- * This API is used for creating a file
+ * Create a file record.
+ * @note This is only one of several steps needed to create a file in CiviCRM.
+ * Use the "Attachment" api to better handle all steps.
  *
  * @param array $params
- *   An associative array of name/value property values of civicrm_file.
+ *   Array per getfields metadata.
  *
  * @return array
  *   Array of newly created file property values.
@@ -59,7 +55,15 @@ function civicrm_api3_file_create($params) {
   }
 
   $fileDAO = new CRM_Core_DAO_File();
-  $properties = array('id', 'file_type_id', 'mime_type', 'uri', 'document', 'description', 'upload_date');
+  $properties = array(
+    'id',
+    'file_type_id',
+    'mime_type',
+    'uri',
+    'document',
+    'description',
+    'upload_date',
+  );
 
   foreach ($properties as $name) {
     if (array_key_exists($name, $params)) {
@@ -78,11 +82,8 @@ function civicrm_api3_file_create($params) {
 /**
  * Get a file.
  *
- * This api is used for finding an existing file.
- * Required parameters : id OR file_type_id of a file
- *
  * @param array $params
- *   An associative array of name/value property values of civicrm_file.
+ *   Array per getfields metadata.
  *
  * @return array
  *   Array of all found file object property values.
@@ -93,12 +94,11 @@ function civicrm_api3_file_get($params) {
 }
 
 /**
- * Update an existing file
- *
- * This api is used for updating an existing file.
- * Required parameters : id of a file
+ * Update an existing file.
  *
  * @param array $params
+ *   Array per getfields metadata.
+ *
  * @return array
  */
 function civicrm_api3_file_update($params) {
@@ -122,12 +122,10 @@ function civicrm_api3_file_update($params) {
 }
 
 /**
- * Deletes an existing file
- *
- * This API is used for deleting a file
- * Required parameters : id of a file
+ * Delete an existing file.
  *
  * @param array $params
+ *   Array per getfields metadata.
  *
  * @return array
  *   API result array