DB: cleaned up documentation

tripal_analysis/tripal_analysis.module

@@ -97,6 +97,7 @@ function tripal_analysis_help ($path, $arg) {
 
 /**
  *  Implements hook_permission().
+ *
  *  Set the permission types that the chado module uses.  Essentially we
  *  want permissionis that protect creation, editing and deleting of chado
  *  data objects

tripal_db/api/tripal_db.api.inc

@@ -1,7 +1,11 @@
 <?php
-
 /**
+ * @file
+ * Provides an application programming interface (API) to manage references to
+ * external databases
+ */
 
+/**
  * @defgroup tripal_db_api Database Reference API
  * @ingroup tripal_api
  * @{
@@ -10,7 +14,7 @@
  */
 
 /**
- * Purpose: To retrieve a chado database object
+ * To retrieve a chado database object
  *
  * @param $select_values
  *   An array meant to uniquely select a given database
@@ -70,7 +74,7 @@ function tripal_db_get_db($select_values) {
 }
 
 /**
- * Purpose: To retrieve a chado db object
+ * To retrieve a chado db object
  *
  * @param $db_id
  *   db.db_id
@@ -86,7 +90,7 @@ function tripal_db_get_db_by_db_id($db_id) {
 }
 
 /**
- * Purpose: To retrieve a chado db object
+ * To retrieve a chado db object
  *
  * @param $name
  *   db.name
@@ -112,21 +116,8 @@ function tripal_db_get_db_by_name($name) {
   }
 }
 
-// Purpose: To retrieve a chado db object
-//
-// @params where_options: array(
-//                          <column_name> => array(
-//                            'type' => <type of column: INT/**STRING>,
-//                            'value' => <the vlaue you want to filter on>,
-//                            'exact' => <if TRUE use =; if FALSE use ~>,
-//                          )
-//        )
-// @return chado db object with all fields from the chado db table
-//
-//function tripal_db_get_db ($where_options) {
-
 /**
- * Purpose: Create an options array to be used in a form element
+ * Create an options array to be used in a form element
  *   which provides a list of all chado dbs
  *
  * @return
@@ -147,21 +138,8 @@ function tripal_db_get_db_options() {
 
 }
 
-// Purpose: To retrieve a chado dbxref object
-//
-// @param where_options: array(
-//                          <column_name> => array(
-//                            'type' => <type of column: INT/**STRING>,
-//                            'value' => <the vlaue you want to filter on>,
-//                            'exact' => <if TRUE use =; if FALSE use ~>,
-//                          )
-//        )
-// @return chado dbxref object with all fields from the chado dbxref table
-//
-//function tripal_db_get_dbxref ($where_options) {
-
 /**
- * Purpose: To retrieve a chado database reference object
+ * To retrieve a chado database reference object
  *
  * @param $select_values
  *   An array meant to uniquely select a given database reference
@@ -321,7 +299,9 @@ function tripal_db_add_db($dbname, $description = '', $url = '',
   return $result[0];
 
 }
+
 /**
+ * Add a database reference
  *
  * @ingroup tripal_db_api
  */
@@ -361,7 +341,9 @@ function tripal_db_add_dbxref($db_id, $accession, $version = '', $description =
 }
 
 /**
+ * Add a record to a database reference linking table (ie: feature_dbxref)
  *
+ * @ingroup tripal_db_api
  */
 function tripal_db_add_dbxref_link($linking_table, $dbxref_id, $foreignkey_name, $foreignkey_id) {
 
@@ -388,4 +370,4 @@ function tripal_db_add_dbxref_link($linking_table, $dbxref_id, $foreignkey_name,
   else {
     return FALSE;
   }
-}
+}

tripal_db/includes/tripal_db.admin.inc

@@ -1,7 +1,13 @@
 <?php
+/**
+ * @file
+ * Provide administration of dbs & dbxrefs
+ */
 
 /**
+ * Launchpad for database reference administration
  *
+ * @ingroup tripal_db
  */
 function tripal_db_admin_db_listing() {
   $output = '';
@@ -40,9 +46,8 @@ function tripal_db_admin_db_listing() {
 }
 
 /**
- *
- * @param $form
- * @param $form_state
+ * Form to edit existing databases.
+ * Implements hook_form().
  *
  * @ingroup tripal_db
  */
@@ -108,10 +113,10 @@ function tripal_db_db_edit_form($form, &$form_state) {
   }
   return $form;
 }
+
 /**
- *
- * @param $form
- * @param $form_state
+ * Form to add new databases.
+ * Implements hook_form().
  *
  * @ingroup tripal_db
  */
@@ -127,11 +132,9 @@ function tripal_db_db_add_form($form, $form_state) {
   );
   return $form;
 }
+
 /**
- *
- * @param $form
- * @param $form_state
- * @param $dbid
+ * Fields commmon between the add/edit forms
  *
  * @ingroup tripal_db
  */
@@ -195,28 +198,24 @@ function tripal_db_add_db_form_fields(&$form, $form_state, $dbid = NULL) {
 
 /**
  * Validation fucntion for tripal_db_db_add_form
- * @param $form
- * @param $form_state
  *
  * @ingroup tripal_db
  */
 function tripal_db_db_add_form_validate($form, &$form_state) {
   tripal_db_form_fields_validate($form, $form_state);
 }
+
 /**
  * Validation fucntion for tripal_db_db_edit_form
- * @param unknown_type $form
- * @param unknown_type $form_state
  *
  * @ingroup tripal_db
  */
 function tripal_db_db_edit_form_validate($form, &$form_state) {
   tripal_db_form_fields_validate($form, $form_state);
 }
+
 /**
- * Genetic validation form for shared fields of both the edit and add forms
- * @param $form
- * @param $form_state
+ * Generic form validation for shared fields of both the edit and add forms
  *
  * @ingroup tripal_db
  */
@@ -234,10 +233,9 @@ function tripal_db_form_fields_validate($form, &$form_state) {
     form_set_error('name', 'The database name must be unique');
   }
 }
+
 /**
- *
- * @param $form
- * @param $form_state
+ * Submit for add db form
  *
  * @ingroup tripal_db
  */
@@ -264,9 +262,7 @@ function tripal_db_db_add_form_submit($form, &$form_state) {
 }
 
 /**
- *
- * @param $form
- * @param $form_state
+ * Submit for edit db form
  *
  * @ingroup tripal_db
  */
@@ -307,8 +303,10 @@ function tripal_db_db_edit_form_submit($form, &$form_state) {
     }
   }
 }
+
 /**
  * Ajax callback for the tripal_db_form
+ *
  * @ingroup tripal_db
  */
 function tripal_db_edit_form_ajax($form, $form_state) {
@@ -335,4 +333,4 @@ function tripal_db_edit_form_ajax($form, $form_state) {
   //drupal_set_message('<pre>' . print_r($elements, TRUE) . '</pre>', "status");
 
   return $elements;
-}
+}

tripal_db/tripal_db.install

@@ -1,12 +1,14 @@
 <?php
-
 /**
  * @file
  * Contains functions related to the installation of this module
  */
 
 /**
+ * Implements hook_disable().
  * Disable default views when module is disabled
+ *
+ * @ingroup tripal_db
  */
 function tripal_db_disable() {
 
@@ -21,6 +23,8 @@ function tripal_db_disable() {
 
 /**
  * Implementation of hook_requirements().
+ *
+ * @ingroup tripal_db
  */
 function tripal_db_requirements($phase) {
   $requirements = array();

tripal_db/tripal_db.module

@@ -1,7 +1,11 @@
 <?php
+/**
+ * @file
+ * General functions for the db module
+ */
 
-require_once "api/tripal_db.api.inc";
-require_once "includes/tripal_db.admin.inc";
+require_once 'api/tripal_db.api.inc';
+require_once 'includes/tripal_db.admin.inc';
 
 /**
  * @defgroup tripal_db Database Reference Module
@@ -16,13 +20,7 @@ require_once "includes/tripal_db.admin.inc";
  */
 
 /**
- *
- * @ingroup tripal_db
- */
-function tripal_db_init() {
-
-}
-/**
+ * Implements hook_menu().
  *
  * @ingroup tripal_db
  */
@@ -86,7 +84,8 @@ function tripal_db_menu() {
 }
 
 /**
- * Implements hook_help()
+ * Implements hook_help().
+ (
  * Purpose: Adds a help page to the module list
  */
 function tripal_db_help ($path, $arg) {
@@ -95,7 +94,6 @@ function tripal_db_help ($path, $arg) {
   }
 }
 
-
 /**
  * Implements hook_permission().
  *
@@ -108,26 +106,28 @@ function tripal_db_help ($path, $arg) {
 function tripal_db_permission() {
   return array(
     'administer db cross-references' => array(
-      'title' => t('Administer the list of external databases used for data cross-references.'),
-      'description' => t('Allows the user to add, edit or delete databases stored in the Chado database.'),
+      'title' => t('Administer External Database Cross-references.'),
+      'description' => t('Allows the user to add, edit or delete external databases references stored in the Chado database.'),
     ),
   );
 }
 
 /**
- * Implements hook_views_api()
- * Purpose: Essentially this hook tells drupal that there is views support for
+ * Implements hook_views_api().
+ *
+ * Essentially this hook tells drupal that there is views support for
  *  for this module which then includes tripal_db.views.inc where all the
  *  views integration code is
  *
  * @ingroup tripal_db
  */
 function tripal_db_views_api() {
-  return array('api' => 2.0);
+  return array('api' => 3.0);
 }
 
-
 /**
+ *  Implements hook_theme().
+ *
  *  We need to let drupal know about our theme functions and their arguments.
  *  We create theme functions to allow users of the module to customize the
  *  look and feel of the output generated in this module
@@ -144,4 +144,4 @@ function tripal_db_theme($existing, $type, $theme, $path) {
     )
   );
   return $items;
-}
+}

tripal_db/tripal_db.views_default.inc

@@ -1,6 +1,13 @@
 <?php
 /**
- * Implements hook_views_default_views()
+ * @file
+ * Describe db default views
+ */
+
+/**
+ * Implements hook_views_default_views().
+ *
+ * @ingroup tripal_db
  */
 function tripal_db_views_default_views() {
   $views = array();
@@ -18,6 +25,8 @@ function tripal_db_views_default_views() {
 
 /**
  * Default Admin View for db management
+ *
+ * @ingroup tripal_db
  */
 function tripal_db_defaultview_admin_db_listing() {
 
@@ -197,6 +206,8 @@ function tripal_db_defaultview_admin_db_listing() {
 
 /**
  * Default Admin View for dbxref management
+ *
+ * @ingroup tripal_db
  */
 function tripal_db_defaultview_admin_dbxref_listing() {
 
@@ -368,4 +379,4 @@ function tripal_db_defaultview_admin_dbxref_listing() {
   $handler->display->display_options['menu']['context_only_inline'] = 0;
 
   return $view;
-}
+}