- Patch #716496 by JohnAlbin: documentation updates for theme functions.

2 files changed, 36 insertions, 9 deletions

diff --git a/modules/file/file.field.inc b/modules/file/file.field.inc
index 57c47ae1e..ddd449e7e 100644
--- a/modules/file/file.field.inc
+++ b/modules/file/file.field.inc
@@ -696,7 +696,13 @@ function file_field_widget_process_multiple($element, &$form_state, $form) {
 }
 
 /**
- * Theme an individual file upload widget.
+ * Returns HTML for an individual file upload widget.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - element: A render element representing the widget.
+ *
+ * @ingroup themeable
  */
 function theme_file_widget($variables) {
   $element = $variables['element'];
@@ -715,7 +721,13 @@ function theme_file_widget($variables) {
 }
 
 /**
- * Theme a group of file upload widgets.
+ * Returns HTML for a group of file upload widgets.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - element: A render element representing the widgets.
+ *
+ * @ingroup themeable
  */
 function theme_file_widget_multiple($variables) {
   $element = $variables['element'];
@@ -800,7 +812,7 @@ function theme_file_widget_multiple($variables) {
 }
 
 /**
- * Generate help text based on upload validators.
+ * Returns HTML for help text based on file upload validators.
  *
  * @param $variables
  *   An associative array containing:
@@ -809,8 +821,7 @@ function theme_file_widget_multiple($variables) {
  *   - upload_validators: An array of upload validators as used in
  *     $element['#upload_validators'].
  *
- * @return
- *   A string suitable for a file field description.
+ * @ingroup themeable
  */
 function theme_file_upload_help($variables) {
   $description = $variables['description'];
@@ -882,7 +893,13 @@ function file_field_formatter_view($entity_type, $entity, $field, $instance, $la
 }
 
 /**
- * Theme function for the 'table' formatter.
+ * Returns HTML for a file attachments table.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - items: An array of file attachments.
+ *
+ * @ingroup themeable
  */
 function theme_file_formatter_table($variables) {
   $header = array(t('Attachment'), t('Size'));
diff --git a/modules/file/file.module b/modules/file/file.module
index b3153e647..b925d7c2e 100644
--- a/modules/file/file.module
+++ b/modules/file/file.module
@@ -607,7 +607,13 @@ function file_managed_file_save_upload($element) {
 }
 
 /**
- * Theme a managed file element.
+ * Returns HTML for a managed file element.
+ *
+ * @param $variables
+ *   An associative array containing:
+ *   - element: A render element representing the file.
+ *
+ * @ingroup themeable
  */
 function theme_file_managed_file($variables) {
   $element = $variables['element'];
@@ -621,11 +627,13 @@ function theme_file_managed_file($variables) {
 }
 
 /**
- * Output a link to a file.
+ * Returns HTML for a link to a file.
  *
  * @param $variables
  *   An associative array containing:
  *   - file: A file object to which the link will be created.
+ *
+ * @ingroup themeable
  */
 function theme_file_link($variables) {
   $file = $variables['file'];
@@ -654,11 +662,13 @@ function theme_file_link($variables) {
 }
 
 /**
- * Return an image with an appropriate icon for the given file.
+ * Returns HTML for an image with an appropriate icon for the given file.
  *
  * @param $variables
  *   An associative array containing:
  *   - file: A file object for which to make an icon.
+ *
+ * @ingroup themeable
  */
 function theme_file_icon($variables) {
   $file = $variables['file'];