Issue #1347890 by sven.lauer, xjm, jhogdon: Clean up API docs for file module.

6 files changed, 68 insertions, 49 deletions

diff --git a/modules/file/file.api.php b/modules/file/file.api.php
index 76fb98610..7f20d83f8 100644
--- a/modules/file/file.api.php
+++ b/modules/file/file.api.php
@@ -55,8 +55,8 @@ function hook_file_download_access($field, $entity_type, $entity) {
  * @return
  *   An array of grants, keyed by module name, each with a Boolean grant value.
  *   Return an empty array to assert FALSE. You may choose to return your own
- *   module's value in addition to other grants or to overwrite the values set by
- *   other modules.
+ *   module's value in addition to other grants or to overwrite the values set
+ *   by other modules.
  */
 function hook_file_download_access_alter(&$grants, $field, $entity_type, $entity) {
   // For our example module, we always enforce the rules set by node module.
diff --git a/modules/file/file.css b/modules/file/file.css
index 40451b8ca..bd4a05970 100644
--- a/modules/file/file.css
+++ b/modules/file/file.css
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Admin stylesheet for file module.
+ */
 
 /**
  * Managed file element styles.
diff --git a/modules/file/file.field.inc b/modules/file/file.field.inc
index 2dbd07d7c..7a5697ccb 100644
--- a/modules/file/file.field.inc
+++ b/modules/file/file.field.inc
@@ -312,7 +312,7 @@ function file_field_delete_revision($entity_type, $entity, $field, $instance, $l
 }
 
 /**
- * Decrements a file usage count and attempts to delete it.
+ * Decrements the usage count for a file and attempts to delete it.
  *
  * This function only has an effect if the file being deleted is used only by
  * File module.
@@ -358,12 +358,13 @@ function file_field_is_empty($item, $field) {
 }
 
 /**
- * Determine whether a file should be displayed when outputting field content.
+ * Determines whether a file should be displayed when outputting field content.
  *
  * @param $item
  *   A field item array.
  * @param $field
  *   A field array.
+ *
  * @return
  *   Boolean TRUE if the file will be displayed, FALSE if the file is hidden.
  */
@@ -516,10 +517,11 @@ function file_field_widget_form(&$form, &$form_state, $field, $instance, $langco
 }
 
 /**
- * Get the upload validators for a file field.
+ * Retrieves the upload validators for a file field.
  *
  * @param $field
  *   A field array.
+ *
  * @return
  *   An array suitable for passing to file_save_upload() or the file field
  *   element's '#upload_validators' property.
@@ -545,7 +547,7 @@ function file_field_widget_upload_validators($field, $instance) {
 }
 
 /**
- * Determine the URI for a file field instance.
+ * Determines the URI for a file field instance.
  *
  * @param $field
  *   A field array.
@@ -553,6 +555,7 @@ function file_field_widget_upload_validators($field, $instance) {
  *   A field instance array.
  * @param $data
  *   An array of token objects to pass to token_replace().
+ *
  * @return
  *   A file directory URI with tokens replaced.
  *
@@ -704,10 +707,13 @@ function file_field_widget_process_multiple($element, &$form_state, $form) {
 }
 
 /**
- * Helper function for file_field_widget_process_multiple().
+ * Retrieves the file description from a field field element.
+ *
+ * This helper function is used by file_field_widget_process_multiple().
  *
  * @param $element
  *   The element being processed.
+ *
  * @return
  *   A description of the file suitable for use in the administrative interface.
  */
@@ -725,7 +731,7 @@ function _file_field_get_description_from_element($element) {
 }
 
 /**
- * Submit handler for upload and remove buttons of file_generic fields.
+ * Form submission handler for upload/remove button of file_field_widget_form().
  *
  * This runs in addition to and after file_managed_file_submit().
  *
diff --git a/modules/file/file.module b/modules/file/file.module
index f979a69fb..a9d35d518 100644
--- a/modules/file/file.module
+++ b/modules/file/file.module
@@ -56,7 +56,7 @@ function file_menu() {
 /**
  * Implements hook_element_info().
  *
- * The managed file element may be used independently anywhere in Drupal.
+ * The managed file element may be used anywhere in Drupal.
  */
 function file_element_info() {
   $file_path = drupal_get_path('module', 'file');
@@ -317,7 +317,7 @@ function file_ajax_progress($key) {
 }
 
 /**
- * Determine the preferred upload progress implementation.
+ * Determines the preferred upload progress implementation.
  *
  * @return
  *   A string indicating which upload progress system is available. Either "apc"
@@ -570,7 +570,9 @@ function file_managed_file_validate(&$element, &$form_state) {
 }
 
 /**
- * Submit handler for upload and remove buttons of managed_file elements.
+ * Form submission handler for upload / remove buttons of managed_file elements.
+ *
+ * @see file_managed_file_process()
  */
 function file_managed_file_submit($form, &$form_state) {
   // Determine whether it was the upload or the remove button that was clicked,
@@ -611,10 +613,11 @@ function file_managed_file_submit($form, &$form_state) {
 }
 
 /**
- * Given a managed_file element, save any files that have been uploaded into it.
+ * Saves any files that have been uploaded into a managed_file element.
  *
  * @param $element
  *   The FAPI element whose values are being saved.
+ *
  * @return
  *   The file object representing the file that was saved, or FALSE if no file
  *   was saved.
@@ -761,13 +764,14 @@ function theme_file_icon($variables) {
 }
 
 /**
- * Given a file object, create a URL to a matching icon.
+ * Creates a URL to the icon for a file object.
  *
  * @param $file
  *   A file object.
  * @param $icon_directory
  *   (optional) A path to a directory of icons to be used for files. Defaults to
  *   the value of the "file_icon_directory" variable.
+ *
  * @return
  *   A URL string to the icon, or FALSE if an appropriate icon cannot be found.
  */
@@ -779,13 +783,14 @@ function file_icon_url($file, $icon_directory = NULL) {
 }
 
 /**
- * Given a file object, create a path to a matching icon.
+ * Creates a path to the icon for a file object.
  *
  * @param $file
  *   A file object.
  * @param $icon_directory
  *   (optional) A path to a directory of icons to be used for files. Defaults to
  *   the value of the "file_icon_directory" variable.
+ *
  * @return
  *   A string to the icon as a local path, or FALSE if an appropriate icon could
  *   not be found.
@@ -831,10 +836,11 @@ function file_icon_path($file, $icon_directory = NULL) {
 }
 
 /**
- * Determine the generic icon MIME package based on a file's MIME type.
+ * Determines the generic icon MIME package based on a file's MIME type.
  *
  * @param $file
  *   A file object.
+ *
  * @return
  *   The generic icon MIME package expected for this file.
  */
@@ -962,7 +968,7 @@ function file_icon_map($file) {
  */
 
 /**
- * Gets a list of references to a file.
+ * Retrieves a list of references to a file.
  *
  * @param $file
  *   A file object.
diff --git a/modules/file/tests/file.test b/modules/file/tests/file.test
index 82bbcdf88..7ff738afc 100644
--- a/modules/file/tests/file.test
+++ b/modules/file/tests/file.test
@@ -6,7 +6,7 @@
  */
 
 /**
- * This class provides methods specifically for testing File's field handling.
+ * Provides methods specifically for testing File module's field handling.
  */
 class FileFieldTestCase extends DrupalWebTestCase {
   protected $admin_user;
@@ -27,7 +27,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Get a sample file of the specified type.
+   * Retrieves a sample file of the specified type.
    */
   function getTestFile($type_name, $size = NULL) {
     // Get a file to upload.
@@ -40,14 +40,14 @@ class FileFieldTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Get the fid of the last inserted file.
+   * Retrieves the fid of the last inserted file.
    */
   function getLastFileId() {
     return (int) db_query('SELECT MAX(fid) FROM {file_managed}')->fetchField();
   }
 
   /**
-   * Create a new file field.
+   * Creates a new file field.
    *
    * @param $name
    *   The name of the new field (all lowercase), exclude the "field_" prefix.
@@ -74,7 +74,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Attach a file field to an entity.
+   * Attaches a file field to an entity.
    *
    * @param $name
    *   The name of the new field (all lowercase), exclude the "field_" prefix.
@@ -108,7 +108,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Update an existing file field with new settings.
+   * Updates an existing file field with new settings.
    */
   function updateFileField($name, $type_name, $instance_settings = array(), $widget_settings = array()) {
     $instance = field_info_instance('node', $name, $type_name);
@@ -119,7 +119,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Upload a file to a node.
+   * Uploads a file to a node.
    */
   function uploadNodeFile($file, $field_name, $nid_or_type, $new_revision = TRUE, $extras = array()) {
     $langcode = LANGUAGE_NONE;
@@ -150,7 +150,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Remove a file from a node.
+   * Removes a file from a node.
    *
    * Note that if replacing a file, it must first be removed then added again.
    */
@@ -164,7 +164,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Replace a file within a node.
+   * Replaces a file within a node.
    */
   function replaceNodeFile($file, $field_name, $nid, $new_revision = TRUE) {
     $edit = array(
@@ -177,7 +177,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Assert that a file exists physically on disk.
+   * Asserts that a file exists physically on disk.
    */
   function assertFileExists($file, $message = NULL) {
     $message = isset($message) ? $message : t('File %file exists on the disk.', array('%file' => $file->uri));
@@ -185,7 +185,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Assert that a file exists in the database.
+   * Asserts that a file exists in the database.
    */
   function assertFileEntryExists($file, $message = NULL) {
     entity_get_controller('file')->resetCache();
@@ -195,7 +195,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Assert that a file does not exist on disk.
+   * Asserts that a file does not exist on disk.
    */
   function assertFileNotExists($file, $message = NULL) {
     $message = isset($message) ? $message : t('File %file exists on the disk.', array('%file' => $file->uri));
@@ -203,7 +203,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Assert that a file does not exist in the database.
+   * Asserts that a file does not exist in the database.
    */
   function assertFileEntryNotExists($file, $message) {
     entity_get_controller('file')->resetCache();
@@ -212,7 +212,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
   }
 
   /**
-   * Assert that a file's status is set to permanent in the database.
+   * Asserts that a file's status is set to permanent in the database.
    */
   function assertFileIsPermanent($file, $message = NULL) {
     $message = isset($message) ? $message : t('File %file is permanent.', array('%file' => $file->uri));
@@ -221,7 +221,7 @@ class FileFieldTestCase extends DrupalWebTestCase {
 }
 
 /**
- * Test class for testing the 'managed_file' element type on its own, not as part of a file field.
+ * Tests the 'managed_file' element type.
  *
  * @todo Create a FileTestCase base class and move FileFieldTestCase methods
  *   that aren't related to fields into it.
@@ -311,7 +311,7 @@ class FileManagedFileElementTestCase extends FileFieldTestCase {
 }
 
 /**
- * Test class to test file field widget, single and multi-valued, with and without Ajax, with public and private files.
+ * Tests file field widget.
  */
 class FileFieldWidgetTestCase extends FileFieldTestCase {
   public static function getInfo() {
@@ -323,7 +323,7 @@ class FileFieldWidgetTestCase extends FileFieldTestCase {
   }
 
   /**
-   * Tests upload and remove buttons, with and without Ajax, for a single-valued File field.
+   * Tests upload and remove buttons for a single-valued File field.
    */
   function testSingleValuedWidget() {
     // Use 'page' instead of 'article', so that the 'article' image field does
@@ -380,7 +380,7 @@ class FileFieldWidgetTestCase extends FileFieldTestCase {
   }
 
   /**
-   * Tests upload and remove buttons, with and without Ajax, for multiple multi-valued File field.
+   * Tests upload and remove buttons for multiple multi-valued File fields.
    */
   function testMultiValuedWidget() {
     // Use 'page' instead of 'article', so that the 'article' image field does
@@ -616,7 +616,7 @@ class FileFieldWidgetTestCase extends FileFieldTestCase {
 }
 
 /**
- * Test class to test file handling with node revisions.
+ * Tests file handling with node revisions.
  */
 class FileFieldRevisionTestCase extends FileFieldTestCase {
   public static function getInfo() {
@@ -628,7 +628,7 @@ class FileFieldRevisionTestCase extends FileFieldTestCase {
   }
 
   /**
-   * Test creating multiple revisions of a node and managing the attached files.
+   * Tests creating multiple revisions of a node and managing attached files.
    *
    * Expected behaviors:
    *  - Adding a new revision will make another entry in the field table, but
@@ -731,7 +731,7 @@ class FileFieldRevisionTestCase extends FileFieldTestCase {
 }
 
 /**
- * Test class to check that formatters are working properly.
+ * Tests that formatters are working properly.
  */
 class FileFieldDisplayTestCase extends FileFieldTestCase {
   public static function getInfo() {
@@ -743,7 +743,7 @@ class FileFieldDisplayTestCase extends FileFieldTestCase {
   }
 
   /**
-   * Test normal formatter display on node display.
+   * Tests normal formatter display on node display.
    */
   function testNodeDisplay() {
     $field_name = strtolower($this->randomName());
@@ -795,7 +795,7 @@ class FileFieldDisplayTestCase extends FileFieldTestCase {
 }
 
 /**
- * Test class to check for various validations.
+ * Tests various validations.
  */
 class FileFieldValidateTestCase extends FileFieldTestCase {
   protected $field;
@@ -810,7 +810,7 @@ class FileFieldValidateTestCase extends FileFieldTestCase {
   }
 
   /**
-   * Test required property on file fields.
+   * Tests the required property on file fields.
    */
   function testRequired() {
     $type_name = 'article';
@@ -858,7 +858,7 @@ class FileFieldValidateTestCase extends FileFieldTestCase {
   }
 
   /**
-   * Test the max file size validator.
+   * Tests the max file size validator.
    */
   function testFileMaxSize() {
     $type_name = 'article';
@@ -910,7 +910,7 @@ class FileFieldValidateTestCase extends FileFieldTestCase {
   }
 
   /**
-   * Test the file extension, do additional checks if mimedetect is installed.
+   * Tests file extension checking.
    */
   function testFileExtension() {
     $type_name = 'article';
@@ -956,7 +956,7 @@ class FileFieldValidateTestCase extends FileFieldTestCase {
 }
 
 /**
- * Test class to check that files are uploaded to proper locations.
+ * Tests that files are uploaded to proper locations.
  */
 class FileFieldPathTestCase extends FileFieldTestCase {
   public static function getInfo() {
@@ -968,7 +968,7 @@ class FileFieldPathTestCase extends FileFieldTestCase {
   }
 
   /**
-   * Test normal formatter display on node display.
+   * Tests the normal formatter display on node display.
    */
   function testUploadPath() {
     $field_name = strtolower($this->randomName());
@@ -1013,7 +1013,7 @@ class FileFieldPathTestCase extends FileFieldTestCase {
   }
 
   /**
-   * A loose assertion to check that a file is uploaded to the right location.
+   * Asserts that a file is uploaded to the right location.
    *
    * @param $expected_path
    *   The location where the file is expected to be uploaded. Duplicate file
@@ -1036,7 +1036,7 @@ class FileFieldPathTestCase extends FileFieldTestCase {
 }
 
 /**
- * Test file token replacement in strings.
+ * Tests the file token replacement in strings.
  */
 class FileTokenReplaceTestCase extends FileFieldTestCase {
   public static function getInfo() {
@@ -1108,7 +1108,7 @@ class FileTokenReplaceTestCase extends FileFieldTestCase {
 }
 
 /**
- * Test class to test file access on private nodes.
+ * Tests file access on private nodes.
  */
 class FilePrivateTestCase extends FileFieldTestCase {
   public static function getInfo() {
@@ -1126,7 +1126,7 @@ class FilePrivateTestCase extends FileFieldTestCase {
   }
 
   /**
-   * Uploads a file to a private node, then tests that access is allowed and denied when appropriate.
+   * Tests file access for file uploaded to a private node.
    */
   function testPrivateFile() {
     // Use 'page' instead of 'article', so that the 'article' image field does
diff --git a/modules/file/tests/file_module_test.module b/modules/file/tests/file_module_test.module
index ea65981ca..358c8b011 100644
--- a/modules/file/tests/file_module_test.module
+++ b/modules/file/tests/file_module_test.module
@@ -22,7 +22,10 @@ function file_module_test_menu() {
 }
 
 /**
- * Form builder for testing a 'managed_file' element.
+ * Form constructor for testing a 'managed_file' element.
+ *
+ * @see file_module_test_form_submit()
+ * @ingroup forms
  */
 function file_module_test_form($form, &$form_state, $tree = TRUE, $extended = FALSE, $default_fid = NULL) {
   $form['#tree'] = (bool) $tree;