From 17817645bda801280ef560ae619cae8d1dc5a1cc Mon Sep 17 00:00:00 2001
From: Earl Miles <merlin@logrus.com>
Date: Fri, 11 Apr 2008 08:41:00 +0000
Subject: [PATCH] Some documentation stubs and cleanup.

---
 docs/docs.php                | 137 +++++++++++++++++++++++++++++++++++
 includes/field.handlers.inc  |   4 +-
 includes/filter.handlers.inc |   7 --
 includes/plugins.inc         |  12 ++-
 includes/query.inc           |   4 +-
 includes/sort.handlers.inc   |   6 ++
 modules/profile.views.inc    |   2 +-
 modules/search.views.inc     |   2 +-
 modules/taxonomy.views.inc   |   4 +-
 modules/upload.views.inc     |  13 ++--
 modules/user.views.inc       |   4 +-
 11 files changed, 168 insertions(+), 27 deletions(-)
 create mode 100644 docs/docs.php

diff --git a/docs/docs.php b/docs/docs.php
new file mode 100644
index 000000000..1a4fb668c
--- /dev/null
+++ b/docs/docs.php
@@ -0,0 +1,137 @@
+<?php
+// $Id$
+/**
+ * @file
+ * This file contains no working PHP code; it exists to provide additional documentation
+ * for doxygen as well as to document hooks in the standard Drupal manner.
+ */
+
+/**
+ * @mainpage Views 2 API Manual
+ *
+ * This is a stub for the main page.
+ *
+ * Topics:
+ * - @ref view_lifetime
+ * - @ref views_hooks
+ * - @ref views_handlers
+ * - @ref views_plugins
+ */
+
+/**
+ * @page view_lifetime The life of a view
+ *
+ * This page explains the basic cycle of a view and what processes happen.
+ */
+
+/**
+ * @page views_handlers About Views' handlers
+ *
+ * This page explains what views handlers are, how they're written, and what
+ * the basic conventions are.
+ *
+ * - @ref views_field_handlers
+ * - @ref views_sort_handlers
+ * - @ref views_filter_handlers
+ * - @ref views_argument_handlers
+ * - @ref views_relationship_handlers
+ */
+
+/**
+ * @page views_plugins About Views' plugins
+ *
+ * This page explains what views plugins are, how they're written, and what
+ * the basic conventions are.
+ *
+ * - @ref views_display_plugins
+ * - @ref views_style_plugins
+ * - @ref views_row_plugins
+ */
+
+/**
+ * @defgroup views_hooks Views' hooks
+ * @{
+ * Hooks that can be implemented by other modules in order to implement the
+ * Views API.
+ */
+
+/**
+ * Stub hook documentation
+ *
+ * This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.
+ * This must either be in the same directory as the .module file or in a subdirectory
+ * named 'includes'.
+ */
+function hook_views_data() {
+  // example code here
+}
+
+/**
+ * Stub hook documentation
+ *
+ * This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.
+ * This must either be in the same directory as the .module file or in a subdirectory
+ * named 'includes'.
+ */
+function hook_views_plugins() {
+  // example code here
+}
+
+/**
+ * Stub hook documentation
+ *
+ * This hook should be placed in MODULENAME.views_default.inc and it will be auto-loaded.
+ * This must either be in the same directory as the .module file or in a subdirectory
+ * named 'includes'.
+ */
+function hook_views_default_views() {
+  // example code here
+}
+
+/**
+ * Stub hook documentation
+ *
+ * This hook should be placed in MODULENAME.views_convert.inc and it will be auto-loaded.
+ * This must either be in the same directory as the .module file or in a subdirectory
+ * named 'includes'.
+ */
+function hook_views_convert() {
+  // example code here
+}
+
+/**
+ * Stub hook documentation
+ */
+function hook_views_query_substitutions() {
+  // example code here
+}
+
+/**
+ * Stub hook documentation
+ *
+ * This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.
+ * This must either be in the same directory as the .module file or in a subdirectory
+ * named 'includes'.
+ *
+ * @todo -- this hook is not yet implemented
+ */
+function hook_views_pre_view() {
+  // example code here
+}
+
+/**
+ * Stub hook documentation
+ *
+ * This hook should be placed in MODULENAME.views.inc and it will be auto-loaded.
+ * This must either be in the same directory as the .module file or in a subdirectory
+ * named 'includes'.
+ *
+ * @todo -- this hook is not yet implemented
+ */
+function hook_views_post_view() {
+  // example code here
+}
+
+/**
+ * @}
+ */
diff --git a/includes/field.handlers.inc b/includes/field.handlers.inc
index e38f02e8f..49fb338b5 100644
--- a/includes/field.handlers.inc
+++ b/includes/field.handlers.inc
@@ -369,8 +369,8 @@ class views_handler_field_prerender_list extends views_handler_field {
     );
   }
 
-  function render($value) {
-    $field = $value->{$this->field_alias};
+  function render($values) {
+    $field = $values->{$this->field_alias};
     if (!empty($this->items[$field])) {
       if ($this->options['type'] == 'separator') {
         return implode(check_plain($this->options['separator']), $this->items[$field]);
diff --git a/includes/filter.handlers.inc b/includes/filter.handlers.inc
index d7acb71c7..636017627 100644
--- a/includes/filter.handlers.inc
+++ b/includes/filter.handlers.inc
@@ -4,11 +4,6 @@
  * @file
  * Views' filter handlers.
  */
-/**
- * @defgroup views_sort_handlers Views' sort handlers
- * @{
- * Handlers to tell Views how to sort queries
- */
 
 /**
  * @defgroup views_filter_handlers Views' filter handlers
@@ -1292,5 +1287,3 @@ class views_handler_filter_many_to_one extends views_handler_filter_in_operator
 /**
  * @}
  */
-
-
diff --git a/includes/plugins.inc b/includes/plugins.inc
index c51cbd961..648b8397a 100644
--- a/includes/plugins.inc
+++ b/includes/plugins.inc
@@ -133,7 +133,7 @@ function views_discover_plugins() {
 }
 
 /**
- * @defgroup views_plugin_displays Views' display plugins
+ * @defgroup views_display_plugins Views' display plugins
  * @{
  * Display plugins control how Views interact with the rest of Drupal.
  *
@@ -141,6 +141,8 @@ function views_discover_plugins() {
  * handle creating Views from a Drupal block hook. They can also
  * handle creating Views from an external module source, such as
  * a Panels pane, or an insert view, or a CCK field type.
+ *
+ * @see hook_views_plugins
  */
 
 /**
@@ -1681,7 +1683,7 @@ class views_plugin_display_block extends views_plugin_display {
  */
 
 /**
- * @defgroup views_plugin_styles Views' style plugins
+ * @defgroup views_style_plugins Views' style plugins
  * @{
  * Style plugins control how a view is rendered. For example, they
  * can choose to display a collection of fields, node_view() output,
@@ -1690,6 +1692,8 @@ class views_plugin_display_block extends views_plugin_display {
  * Many style plugins can have an optional 'row' plugin, that displays
  * a single record. Not all style plugins can utilize this, so it is
  * up to the plugin to set this up and call through to the row plugin.
+ *
+ * @see hook_views_plugins
  */
 
 /**
@@ -2190,12 +2194,14 @@ class views_plugin_style_summary extends views_plugin_style {
  */
 
 /**
- * @defgroup views_plugin_rows Views' row plugins
+ * @defgroup views_row_plugins Views' row plugins
  * @{
  *
  * Row plugins control how Views outputs an individual record. They are
  * tightly coupled to style plugins, in that a style plugin is what calls
  * the row plugin.
+ *
+ * @see hook_views_plugins
  */
 
 /**
diff --git a/includes/query.inc b/includes/query.inc
index b2c95329f..a0915c652 100644
--- a/includes/query.inc
+++ b/includes/query.inc
@@ -464,9 +464,9 @@ class views_query {
   /**
    * Retrieve join data from the larger join data cache.
    *
-   * @param
+   * @param $table
    *   The table to get the join information for.
-   * @param
+   * @param $base_table
    *   The path we're following to get this join.
    *
    * @return
diff --git a/includes/sort.handlers.inc b/includes/sort.handlers.inc
index c741b164e..be46fc5a8 100644
--- a/includes/sort.handlers.inc
+++ b/includes/sort.handlers.inc
@@ -5,6 +5,12 @@
  * Views' sort handlers.
  */
 
+/**
+ * @defgroup views_sort_handlers Views' sort handlers
+ * @{
+ * Handlers to tell Views how to sort queries
+ */
+
 /**
  * Base sort handler that has no options and performs a simple sort
  */
diff --git a/modules/profile.views.inc b/modules/profile.views.inc
index 73c03927e..c9e0c6f66 100644
--- a/modules/profile.views.inc
+++ b/modules/profile.views.inc
@@ -6,7 +6,7 @@
  */
 
 /**
- * @defgroup views_user_module user.module handlers
+ * @defgroup views_profile_module profile.module handlers
  *
  * @{
  */
diff --git a/modules/search.views.inc b/modules/search.views.inc
index daccfce24..c5e0d4952 100644
--- a/modules/search.views.inc
+++ b/modules/search.views.inc
@@ -6,7 +6,7 @@
  */
 
 /**
- * @defgroup views_node_module node.module handlers
+ * @defgroup views_search_module search.module handlers
  *
  * Includes the tables 'search_index'
  * @{
diff --git a/modules/taxonomy.views.inc b/modules/taxonomy.views.inc
index 5c32b1757..0bd0ec975 100644
--- a/modules/taxonomy.views.inc
+++ b/modules/taxonomy.views.inc
@@ -353,10 +353,10 @@ class views_handler_field_term_node_tid extends views_handler_field_prerender_li
     $this->add_additional_fields();
   }
 
-  function pre_render($results) {
+  function pre_render($values) {
     $this->field_alias = $this->aliases['nid'];
     $nids = array();
-    foreach ($results as $result) {
+    foreach ($values as $result) {
       $nids[] = $result->{$this->aliases['nid']};
     }
 
diff --git a/modules/upload.views.inc b/modules/upload.views.inc
index 7d6f31e0e..185331419 100644
--- a/modules/upload.views.inc
+++ b/modules/upload.views.inc
@@ -149,12 +149,12 @@ class views_handler_field_upload_fid extends views_handler_field_prerender_list
     $this->field_alias = $this->aliases['nid'];
   }
 
-  function pre_render($results) {
+  function pre_render($values) {
     $nids = array();
     $this->items = array();
 
     $data = array();
-    foreach ($results as $result) {
+    foreach ($values as $result) {
       $nids[] = $result->{$this->aliases['nid']};
     }
 
@@ -207,7 +207,7 @@ class views_handler_field_upload_description extends views_handler_field_prerend
     );
   }
 
-  function pre_render($results) {
+  function pre_render($values) {
     if (empty($this->options['link_to_file'])) {
       return;
     }
@@ -216,7 +216,7 @@ class views_handler_field_upload_description extends views_handler_field_prerend
     $this->items = array();
 
     $data = array();
-    foreach ($results as $result) {
+    foreach ($values as $result) {
       $fids[] = $result->{$this->aliases['fid']};
     }
 
@@ -229,9 +229,8 @@ class views_handler_field_upload_description extends views_handler_field_prerend
     }
   }
 
-  function render($value) {
-    return $this->render_link($value->{$this->field_alias}, $value);
-
+  function render($values) {
+    return $this->render_link($values->{$this->field_alias}, $values);
   }
 
   /**
diff --git a/modules/user.views.inc b/modules/user.views.inc
index 9d9934a66..4dbc485b4 100644
--- a/modules/user.views.inc
+++ b/modules/user.views.inc
@@ -496,11 +496,11 @@ class views_handler_field_user_roles extends views_handler_field_prerender_list
     $this->field_alias = $this->aliases['uid'];
   }
 
-  function pre_render($results) {
+  function pre_render($values) {
     $uids = array();
     $this->items = array();
 
-    foreach ($results as $result) {
+    foreach ($values as $result) {
       $uids[] = $result->{$this->aliases['uid']};
     }
 
-- 
GitLab