Skip to content

GitLab

Commit d91203fe authored by catch's avatar catch
Browse files

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

parent f28b98cb
Hide whitespace changes
Inline Side-by-side
Showing with 115 additions and 65 deletions
core/modules/file/file.admin.css
View file @ d91203fe
/**
* @file
* Admin styles for file module.
* Admin stylesheet for file module.
*/
/**
......
core/modules/file/file.api.php
View file @ d91203fe
......@@ -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.
......
core/modules/file/file.field.inc
View file @ d91203fe
......@@ -120,9 +120,13 @@ function file_field_instance_settings_form($field, $instance) {
}
/**
* Element validate callback for the maximum upload size field.
* Render API callback: Validates the maximum uplodad size field.
*
* Ensure a size that can be parsed by parse_size() has been entered.
* Ensures that a size has been entered and that it can be parsed by
* parse_size().
*
* This function is assigned as an #element_validate callback in
* file_field_instance_settings_form().
*/
function _file_generic_settings_max_filesize($element, &$form_state) {
if (!empty($element['#value']) && !is_numeric(parse_size($element['#value']))) {
......@@ -131,7 +135,10 @@ function _file_generic_settings_max_filesize($element, &$form_state) {
}
/**
* Element validate callback for the allowed file extensions field.
* Render API callback: Validates the allowed file extensions field.
*
* This function is assigned as an #element_validate callback in
* file_field_instance_settings_form().
*
* This doubles as a convenience clean-up function and a validation routine.
* Commas are allowed by the end-user, but ultimately the value will be stored
......@@ -152,10 +159,14 @@ function _file_generic_settings_extensions($element, &$form_state) {
}
/**
* Element validate callback for the file destination field.
* Render API callback: Validates the file destination field.
*
* Removes slashes from the beginning and end of the destination value and
* ensures that the file directory path is not included at the beginning of the
* value.
*
* Remove slashes from the beginning and end of the destination value and ensure
* that the file directory path is not included at the beginning of the value.
* This function is assigned as an #element_validate callback in
* file_field_instance_settings_form().
*/
function _file_generic_settings_file_directory_validate($element, &$form_state) {
// Strip slashes from the beginning and end of $widget['file_directory'].
......@@ -312,7 +323,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 +369,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 +528,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 +558,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 +566,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.
*
......@@ -568,7 +582,9 @@ function file_field_widget_uri($field, $instance, $data = array()) {
}
/**
* The #value_callback for the file_generic field element.
* Render API callback: Retrieves the value for the file_generic field element.
*
* This function is assigned as a #value callback in file_field_widget_form().
*/
function file_field_widget_value($element, $input = FALSE, $form_state) {
if ($input) {
......@@ -594,9 +610,11 @@ function file_field_widget_value($element, $input = FALSE, $form_state) {
}
/**
* An element #process callback for the file_generic field type.
* Render API callback: Processes a file_generic field element.
*
* Expands the file_generic type to include the description and display fields.
*
* This function is assigned as a #process callback in file_field_widget_form().
*/
function file_field_widget_process($element, &$form_state, $form) {
$item = $element['#value'];
......@@ -665,10 +683,12 @@ function file_field_widget_process($element, &$form_state, $form) {
}
/**
* An element #process callback for a group of file_generic fields.
* Render API callback: Processes a group of file_generic field elements.
*
* Adds the weight field to each row so it can be ordered and adds a new Ajax
* wrapper around the entire group so it can be replaced all at once.
*
* This function is assigned as a #process callback in file_field_widget_form().
*/
function file_field_widget_process_multiple($element, &$form_state, $form) {
$element_children = element_children($element, TRUE);
......@@ -704,10 +724,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 +748,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().
*
......
core/modules/file/file.module
View file @ d91203fe
......@@ -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');
......@@ -223,12 +223,16 @@ function file_file_download($uri, $field_type = 'file') {
}
/**
* Menu callback; Shared Ajax callback for file uploads and deletions.
* Ajax callback: Processes file uploads and deletions.
*
* Path: file/ajax
*
* This rebuilds the form element for a particular field item. As long as the
* form processing is properly encapsulated in the widget element the form
* should rebuild correctly using FAPI without the need for additional callbacks
* or processing.
*
* @see file_menu()
*/
function file_ajax_upload() {
$form_parents = func_get_args();
......@@ -286,7 +290,9 @@ function file_ajax_upload() {
}
/**
* Menu callback for upload progress.
* Ajax callback: Retrieves upload progress.
*
* Path: file/progress
*
* @param $key
* The unique key for this upload process.
......@@ -317,7 +323,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"
......@@ -348,10 +354,12 @@ function file_file_delete($file) {
}
/**
* Process function to expand the managed_file element type.
* Render API callback: Expands the managed_file element type.
*
* Expands the file type to include Upload and Remove buttons, as well as
* support for a default value.
*
* This function is assigned as a #process callback in file_element_info().
*/
function file_managed_file_process($element, &$form_state, $form) {
$fid = isset($element['#value']['fid']) ? $element['#value']['fid'] : 0;
......@@ -471,7 +479,9 @@ function file_managed_file_process($element, &$form_state, $form) {
}
/**
* The #value_callback for a managed_file type element.
* Render API callback: Determines the value for a managed_file type element.
*
* This function is assigned as a #value_callback in file_element_info().
*/
function file_managed_file_value(&$element, $input = FALSE, $form_state = NULL) {
$fid = 0;
......@@ -537,7 +547,10 @@ function file_managed_file_value(&$element, $input = FALSE, $form_state = NULL)
}
/**
* An #element_validate callback for the managed_file element.
* Render API callback: Validates the managed_file element.
*
* This function is assigned as a #element_validate callback in
* file_element_info().
*/
function file_managed_file_validate(&$element, &$form_state) {
// If referencing an existing file, only allow if there are existing
......@@ -570,7 +583,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 +626,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.
......@@ -671,7 +687,7 @@ function theme_file_managed_file($variables) {
}
/**
* #pre_render callback to hide display of the upload or remove controls.
* Render API callback: Hides display of the upload or remove controls.
*
* Upload controls are hidden when a file is already uploaded. Remove controls
* are hidden when there is no file attached. Controls are hidden here instead
......@@ -686,6 +702,8 @@ function theme_file_managed_file($variables) {
* assume that the buttons can't be "clicked" just because they are not
* displayed.
*
* This function is assigned as a #pre_render callback in file_element_info().
*
* @see file_managed_file_process()
* @see form_builder()
*/
......@@ -761,13 +779,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 +798,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 +851,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 +983,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.
......
core/modules/file/tests/file.test
View file @ d91203fe
......@@ -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());
......@@ -782,7 +782,7 @@ class FileFieldDisplayTestCase extends FileFieldTestCase {
}
/**
* Test class to check for various validations.
* Tests various validations.
*/
class FileFieldValidateTestCase extends FileFieldTestCase {
protected $field;
......@@ -797,7 +797,7 @@ class FileFieldValidateTestCase extends FileFieldTestCase {
}
/**
* Test required property on file fields.
* Tests the required property on file fields.
*/
function testRequired() {
$type_name = 'article';
......@@ -845,7 +845,7 @@ class FileFieldValidateTestCase extends FileFieldTestCase {
}
/**
* Test the max file size validator.
* Tests the max file size validator.
*/
function testFileMaxSize() {
$type_name = 'article';
......@@ -897,7 +897,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';
......@@ -943,7 +943,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() {
......@@ -955,7 +955,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());
......@@ -1000,7 +1000,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
......@@ -1023,7 +1023,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() {
......@@ -1095,7 +1095,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() {
......@@ -1113,7 +1113,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
......
core/modules/file/tests/file_module_test.module
View file @ d91203fe
......@@ -22,7 +22,13 @@ function file_module_test_menu() {
}
/**
* Form builder for testing a 'managed_file' element.
* Form constructor for testing a 'managed_file' element.
*
* Path: file/test
*
* @see file_module_test_menu()
* @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;
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment