- Patch #681538 by aspilicious, jhodgdon: improved documentation, better @see also links.

5 files changed, 21 insertions, 22 deletions

diff --git a/includes/common.inc b/includes/common.inc
index d04f938ea..ebbadc125 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -4559,7 +4559,7 @@ function _drupal_bootstrap_full() {
  * Page compression requires the PHP zlib extension
  * (http://php.net/manual/en/ref.zlib.php).
  *
- * @see drupal_page_header
+ * @see drupal_page_header()
  */
 function drupal_page_set_cache() {
   global $base_root;
diff --git a/includes/database/schema.inc b/includes/database/schema.inc
index 670d3ab3b..0437999d2 100644
--- a/includes/database/schema.inc
+++ b/includes/database/schema.inc
@@ -300,7 +300,7 @@ abstract class DatabaseSchema implements QueryPlaceholderInterface {
    *   table along with adding the field. The format is the same as a
    *   table specification but without the 'fields' element. If you are
    *   adding a type 'serial' field, you MUST specify at least one key
-   *   or index including it in this array. @see db_change_field for more
+   *   or index including it in this array. See db_change_field() for more
    *   explanation why.
    */
   abstract public function addField($table, $field, $spec, $keys_new = array());
diff --git a/includes/form.inc b/includes/form.inc
index 401c881b4..7e86bcb43 100644
--- a/includes/form.inc
+++ b/includes/form.inc
@@ -2457,22 +2457,16 @@ function theme_container($variables) {
 }
 
 /**
- * Format a table with radio buttons or checkboxes.
+ * Formats a table with radio buttons or checkboxes.
  *
  * @param $variables
  *   An associative array containing:
  *   - element: An associative array containing the properties and children of
- *     the tableselect element.
- *     Each option in $variables['element']['#options'] can contain an array
- *     keyed by '#attributes' which is added to the row's HTML attributes.
- *     @see theme_table
- *     Properties used: header, options, empty, js_select.
- *
- * @return
- *   A themed HTML string representing the table.
- *
- * Example:
- *
+ *     the tableselect element. Properties used: #header, #options, #empty,
+ *     and #js_select. The #options property is an array of selection options;
+ *     each array element of #options is an array of properties. These 
+ *     properties can include #attributes, which is added to the
+ *     table row's HTML attributes (see theme_table()). Example:
  * @code
  * $options = array();
  * $options[0]['title'] = "A red row"
@@ -2485,6 +2479,11 @@ function theme_container($variables) {
  * '#title' => 'My Selector'
  * '#options' => $options,
  * );
+ * @endcode
+ *
+ * @return
+ *   A themed HTML string representing the table.
+ *
  * @ingroup themeable
  */
 function theme_tableselect($variables) {
diff --git a/includes/theme.inc b/includes/theme.inc
index eeb7a5faf..b1b2f0314 100644
--- a/includes/theme.inc
+++ b/includes/theme.inc
@@ -2357,8 +2357,8 @@ function template_preprocess_html(&$variables) {
  * Any changes to variables in this preprocessor should also be changed inside
  * template_preprocess_maintenance_page() to keep all of them consistent.
  *
- * @see drupal_render_page
- * @see template_process_page
+ * @see drupal_render_page()
+ * @see template_process_page()
  * @see page.tpl.php
  */
 function template_preprocess_page(&$variables) {
diff --git a/includes/updater.inc b/includes/updater.inc
index 173ea2deb..074d3780d 100644
--- a/includes/updater.inc
+++ b/includes/updater.inc
@@ -198,11 +198,11 @@ class Updater {
    * Updates a Drupal project, returns a list of next actions.
    *
    * @param FileTransfer $filetransfer
-   *   Object which is a child of FileTransfer. Used for moving files
+   *   Object that is a child of FileTransfer. Used for moving files
    *   to the server.
    * @param array $overrides
-   *   An array of settings to override defaults
-   *   @see self::getInstallArgs
+   *   An array of settings to override defaults; see self::getInstallArgs().
+   *
    * @return array
    *   An array of links which the user may need to complete the update
    */
@@ -254,10 +254,10 @@ class Updater {
    * Installs a Drupal project, returns a list of next actions.
    *
    * @param FileTransfer $filetransfer
-   *   Object which is a child of FileTransfer.
+   *   Object that is a child of FileTransfer.
    * @param array $overrides
-   *   An array of settings to override defaults.
-   *   @see self::getInstallArgs
+   *   An array of settings to override defaults; see self::getInstallArgs().
+   *
    * @return array
    *   An array of links which the user may need to complete the install.
    */