first round api documentation clean up

tripal/api/tripal.entities.api.inc

@@ -509,50 +509,6 @@ function tripal_create_bundle($args, &$error = '') {
   return $bundle;
 }
 
-/*
- * Are we keeping this in?
- * 
- * Checks access permissions for a given entity.
- *
- * This function is set for TripalEntity access checking in the
- * tripal_entity_info() under the 'access callback' element.
- *
- *
- * @param $entity
- *   The entity to check access for.
-
-function tripal_entity_permissions($entity) {
-
-  if ($entity) {
-    $bundle_name = $entity->bundle;
-  }
-  else {
-    return FALSE;
-  }
-
-  // Get the bundle object.
-  $bundle = tripal_load_bundle_entity(array('name' => $bundle_name));
-
-  // Identify the administrative user roles.
-  $admin_role = user_role_load_by_name('administrator');
-  $roles = array($admin_role->rid => $admin_role->name);
-  // Define the permissions.
-  $permission_for_role = array(
-    'create ' . $bundle->label => TRUE,
-    'view ' . $bundle->label => TRUE,
-    'edit ' . $bundle->label => TRUE,
-    'delete ' . $bundle->label => TRUE,
-  );
-  // Assign the permissions
-  foreach($roles as $role => $value){
-    user_role_grant_permissions($role, $permission_for_role);
-    watchdog('debug', '<pre>tripal_entity_permissions  $role: '. print_r($role, TRUE) .'</pre>');
-  }
-
-  return TRUE;
-}
- */
-
 /**
  * Retrieves a list of the content types.
  *
@@ -1392,7 +1348,7 @@ function _tripal_get_bundle_field_element_details($elements, &$field_details) {
  *
  * @throws Exception
  *
- * @ingroup tripal_entities_api
+ * 
  */
 function tripal_insert_entity($bundle_name, $values){
   global $user;
@@ -1448,7 +1404,7 @@ function tripal_insert_entity($bundle_name, $values){
  * @param $bundle_name
  * @param $values
  *
- * @ingroup tripal_entities_api
+ * 
  */
 function tripal_update_entity($bundle_name, $values) {
 

tripal/api/tripal.fields.api.inc

@@ -106,30 +106,7 @@ function hook_bundle_fields_info($entity_type, $bundle) {
 function hook_bundle_instances_info($entity_type, $bundle) {
 
 }
-/**
- * This doesn't appear to be integrated anywhere? 
- * 
- * @param $info
- * @param $bundle
- * @param $term
- *
- * @ingroup tripal_fields_api
- */
-function hook_bundle_fields_info_alter(&$info, $bundle, $term) {
 
-}
-/**
- * This doesn't appear to be integrated anywhere? 
- * 
- * @param $info
- * @param $bundle
- * @param $term
- *
- * @ingroup tripal_fields_api
- */
-function hook_bundle_instances_info_alter(&$info, $bundle, $term) {
-
-}
 /**
  * Retrieves a list of TripalField types.
  *

tripal/api/tripal.importer.api.inc

@@ -12,7 +12,7 @@
  * @ingroup tripal_api
  * @{
  * Provides an application programming interface (API) for working with
- * data file importers using the TripalImporter class.
+ * data file importers using the TripalImporter class into a chado database.
  * @}
  *
  */

tripal/api/tripal.jobs.api.inc

@@ -1,8 +1,8 @@
 <?php
 /**
  * @file
- * Tripal offers a job management subsystem for managing tasks that may require an extended period of time for
- * completion.
+ * Tripal offers a job management subsystem for managing tasks that may require 
+ * an extended period of time for completion.
  */
 
 /**
@@ -39,8 +39,8 @@
  * @param $uid
  *    The uid of the user adding the job
  * @param $priority
- *    The priority at which to run the job where the highest priority is 10 and the lowest priority
- *    is 1. The default priority is 10.
+ *    The priority at which to run the job where the highest priority is 10 and 
+ *    the lowest priority is 1. The default priority is 10.
  * @param $includes
  *    An array of paths to files that should be included in order to execute
  *    the job. Use the module_load_include function to get a path for a given
@@ -60,7 +60,8 @@
  *         $user->uid, $analysis_id, $match_type);
  *
  *   $includes = array()
- *   $includes[] = module_load_include('inc', 'tripal_chado', 'includes/loaders/tripal_chado.fasta_loader');
+ *   $includes[] = module_load_include('inc', 'tripal_chado', 
+ *                                'includes/loaders/tripal_chado.fasta_loader');
  *
  *   tripal_add_job("Import FASTA file: $dfile", 'tripal_feature',
  *     'tripal_feature_load_fasta', $args, $user->uid, 10, $includes);
@@ -231,12 +232,13 @@ function tripal_max_jobs_exceeded($max_jobs) {
 }
 
 /**
- * Set a job to be re-ran (ie: add it back into the job queue)
+ * Set a job to be re-run (ie: add it back into the job queue).
  *
  * @param $job_id
  *   The job_id of the job to be re-ran
  * @param $goto_jobs_page
- *   If set to TRUE then after the re run job is added Drupal will redirect to the jobs page
+ *   If set to TRUE then after the re run job is added Drupal will redirect to 
+ *   the jobs page
  *
  * @ingroup tripal_jobs_api
  */
@@ -287,7 +289,7 @@ function tripal_rerun_job($job_id, $goto_jobs_page = TRUE) {
 }
 
 /**
- * Cancel a Tripal Job currently waiting in the job queue
+ * Cancel a Tripal Job currently waiting in the job queue.
  *
  * @param $job_id
  *   The job_id of the job to be cancelled
@@ -323,7 +325,7 @@ function tripal_cancel_job($job_id, $redirect = TRUE) {
 }
 
 /**
- * A function used to manually launch all queued tripal jobs
+ * A function used to manually launch all queued tripal jobs.
  *
  * @param $do_parallel
  *   A boolean indicating whether jobs should be attempted to run in parallel
@@ -335,7 +337,8 @@ function tripal_cancel_job($job_id, $redirect = TRUE) {
  *   job needs to be launched and this argument will allow it.  Only jobs
  *   which have not been run previously will run.
  * @param $max_jobs
- *   The maximum number of jobs that should be run concurrently. If -1 then unlimited.
+ *   The maximum number of jobs that should be run concurrently. If -1 then 
+ *   unlimited.
  * @param $single
  *   Ensures only a single job is run rather then the entire queue.
  *
@@ -434,7 +437,7 @@ function tripal_launch_job($do_parallel = 0, $job_id = NULL, $max_jobs = -1, $si
 }
 
 /**
- * An internal function for setting the progress for a current job
+ * An internal function for setting the progress for a current job.
  *
  * @param $job_id
  *   The job_id to set the progress for

tripal/api/tripal.notice.api.inc

@@ -2,7 +2,7 @@
 /**
  * @file
  * Provides an application programming interface (API) for improved user
- * notivications.  These API functions can be used to set messages for
+ * notifications.  These API functions can be used to set messages for
  * end-users, administrators, or simple logging.
  */
 
@@ -63,7 +63,7 @@ define('TRIPAL_DEBUG',7);
  */
 function tripal_report_error($type, $severity, $message, $variables = array(), $options = array()) {
 
-  // Get human-readable severity string
+  // Get human-readable severity string.
   $severity_string = '';
   switch ($severity) {
     case TRIPAL_CRITICAL:
@@ -140,7 +140,7 @@ function tripal_report_error($type, $severity, $message, $variables = array(), $
  * tripal administrators.
  *
  * @param $message
- *   The message to be displayed to the tripal administrators
+ *   The message to be displayed to the tripal administrators.
  * @param $importance
  *   The level of importance for this message. In the future this will be used
  *   to allow administrators to filter some of these messages. It can be one of
@@ -167,10 +167,10 @@ function tripal_set_message($message, $importance = TRIPAL_INFO, $options = arra
     return '';
   }
 
-  // set defaults
+  // Set defaults.
   $options['return_html'] = (isset($options['return_html'])) ? $options['return_html'] : FALSE;
 
-  // Get human-readable severity string
+  // Get human-readable severity string.
   $importance_string = '';
   switch ($importance) {
     case TRIPAL_CRITICAL:
@@ -193,7 +193,7 @@ function tripal_set_message($message, $importance = TRIPAL_INFO, $options = arra
       break;
   }
 
-  // Mark-up the Message
+  // Mark-up the Message.
   $full_message =
      '<div class="tripal-site-admin-message">' .
        '<span class="tripal-severity-string ' . strtolower($importance_string) . '">' . $importance_string . ': </span>' .
@@ -201,7 +201,8 @@ function tripal_set_message($message, $importance = TRIPAL_INFO, $options = arra
    '</div>';
 
   // Handle whether to return the HTML & let the caller deal with it
-  // or to use drupal_set_message to put it near the top of the page  & let the theme deal with it
+  // or to use drupal_set_message to put it near the top of the page  & let the 
+  // theme deal with it.
   if ($options['return_html']) {
     return '<div class="messages tripal-site-admin-only">' . $full_message . '</div>';
   }
@@ -211,22 +212,22 @@ function tripal_set_message($message, $importance = TRIPAL_INFO, $options = arra
 }
 
 /**
- * File-based Logging for Tripal
+ * File-based logging for Tripal.
  *
  * @param $message
- *   The message to be logged. Need not contain date/time information
+ *   The message to be logged. Need not contain date/time information.
  * @param $log_type
  *   The type of log. Should be one of 'error' or 'job' although other types
  *   are supported.
  * @param $options
  *   An array of options where the following keys are supported:
  *     - first_progress_bar: this sohuld be used for the first log call for a
- *       progress bar
+ *       progress bar.
  *     - is_progress_bar: this option should be used for all but the first print
  *       of a progress bar to allow it all to be printed on the same line
- *       without intervening date prefixes
+ *       without intervening date prefixes.
  * @return
- *   The number of bytes that were written to the file, or FALSE on failure
+ *   The number of bytes that were written to the file, or FALSE on failure.
  *
  * @ingroup tripal_notify_api
  */
@@ -245,4 +246,3 @@ function tripal_log($message, $type = 'error', $options = array()) {
   return error_log($message);
 
 }
-

tripal/api/tripal.terms.api.inc

@@ -12,7 +12,7 @@
  * Tripal provides an application programming interface (API) for working with
  * controlled vocaublary terms.  Tripal v3 is highly dependent on controlled
  * vocabularies for identifying all content types and fields attached to those
- * content types.  However, Tripal v3 is also database agnostic. Therefore, it
+ * content types.  However, Tripal v3 is also database agnostic. Therefore,
  * controlled vocabularies can be stored in any database back-end.  By default
  * the tripal_chado module is used for storing controlled vocabularies. However,
  * if someone wanted to store controlled vocabularies in a database other than
@@ -85,16 +85,19 @@ function hook_vocab_select_term_form(&$form, &$form_state) {
 
   return $form;
 }
+
 /**
  * Validates the hook_vocab_select_term_form().
  *
- * @param $name
+ * @param $form
+ * @param $form_state
  *
  * @ingroup tripal_terms_api
  */
 function hook_vocab_select_term_form_validate($form, &$form_state) {
 
 }
+
 /**
  * Provides a form for importing vocabularies and their terms.
  *
@@ -111,9 +114,27 @@ function hook_vocab_select_term_form_validate($form, &$form_state) {
 function hook_vocab_import_form($form, &$form_state) {
   return $form;
 }
+
+/**
+ * Validates the hook_vocab_import_form().
+ *
+ * @param $form
+ * @param $form_state
+ *
+ * @ingroup tripal_terms_api
+ */
 function hook_vocab_import_form_validate($form, &$form_state) {
 
 }
+
+/**
+ * Submits the hook_vocab_import_form().
+ *
+ * @param $form
+ * @param $form_state
+ *
+ * @ingroup tripal_terms_api
+ */
 function hook_vocab_import_form_submit($form, &$form_state) {
 
 }
@@ -132,7 +153,7 @@ function hook_vocab_import_form_submit($form, &$form_state) {
  *
  * @return
  *   An array with at least the following keys:
- *     -vocabulary : An associative array with the following keys
+ *     -vocabulary : An associative array with the following keys:
  *       -name:  The short name for the vocabulary (e.g. SO, PATO, etc).
  *       -description: The description of this vocabulary.
  *       -url: The URL for the vocabulary.
@@ -154,6 +175,7 @@ function hook_vocab_get_term($vocabulary, $accession) {
   // See the tripal_chado_vocab_get_term() function for an example.
 
 }
+
 /**
  * Retrieves a paged list of terms from a vocabulary.
  *
@@ -164,10 +186,13 @@ function hook_vocab_get_term($vocabulary, $accession) {
  * @param $element
  *   The pager element. This is equivalent to the element from the
  *   pager_default_initialize() function of Drupal.
+ * 
+ * @ingroup tripal_terms_api
  */
 function hook_vocab_get_terms($vocabulary, $limit = 25, $element = 0) {
-
+  // See the tripal_chado_vocab_get_terms() function for an example.
 }
+
 /**
  * Hook used by the default term storage backend to provide children for a term.
  *
@@ -188,8 +213,9 @@ function hook_vocab_get_terms($vocabulary, $limit = 25, $element = 0) {
  * @ingroup tripal_terms_api
  */
 function hook_vocab_get_term_children($vocabulary, $accession) {
-
+  // See the tripal_chado_vocab_get_term_children() function for an example.
 }
+
 /**
  * Hook used by the default term storage backend to provide root terms.
  *
@@ -208,8 +234,9 @@ function hook_vocab_get_term_children($vocabulary, $accession) {
  * @ingroup tripal_terms_api
  */
 function hook_vocab_get_root_terms($vocabulary) {
-
+  // See the tripal_chado_vocab_get_root_terms() function for an example.
 }
+
 /**
  * Hook used by the default term storage backend to provide details for a vocab.
  *
@@ -231,6 +258,7 @@ function hook_vocab_get_root_terms($vocabulary) {
  *       prefix does not support appending then the exact location for the
  *       position of the short_name and the term accession will be
  *       specified with the {db} and {accession} tags respectively.
+ * 
  * @ingroup tripal_terms_api
  */
 function hook_vocab_get_vocabulary($vocabulary) {
@@ -244,16 +272,19 @@ function hook_vocab_get_vocabulary($vocabulary) {
  *   An array of vocabularies where each entry in the array is compatible
  *   with the array returned by the tripal_get_vocabulary_details()
  *   function.
+ * 
+ * @ingroup tripal_terms_api
  */
 function hook_vocab_get_vocabularies() {
   // See the tripal_chado_vocab_get_vocabularies() function for an example.
 }
+
 /**
  * Hook used by the default term storage backend to add new terms.
  *
  * @param $details
  *   An array with at least the following keys:
- *     -vocabulary : An associative array with the following keys
+ *     -vocabulary : An associative array with the following keys:
  *       -name:  The short name for the vocabulary (e.g. SO, PATO, etc).
  *       -description: The description of this vocabulary.
  *       -url: The URL for the vocabulary.
@@ -268,15 +299,14 @@ function hook_vocab_get_vocabularies() {
  *     -definition : The term's description.
  * @return
  *   TRUE if the term was added, FALSE otherwise.  If the term already exists
- *   it will be updated and the return value will be TRUE,
+ *   it will be updated and the return value will be TRUE.
+ * 
  * @ingroup tripal_terms_api
  */
 function hook_vocab_add_term($details) {
   // See the tripal_chado_vocab_set_term() function for an example.
 }
 
-
-
 /**
  * Adds a term to the vocabulary storage backend.
  *
@@ -295,7 +325,8 @@ function hook_vocab_add_term($details) {
  *     -definition : The term's description.
  * @return
  *   TRUE if the term was added, FALSE otherwise.  If the term already exists
- *   it will be updated and the return value will be TRUE,
+ *   it will be updated and the return value will be TRUE.
+ * 
  * @ingroup tripal_terms_api
  */
 function tripal_add_term($details) {
@@ -362,6 +393,7 @@ function tripal_get_term_details($vocabulary, $accession) {
     }
   }
 }
+
 /**
  * Retrieves the immediate children of the given term.
  *
@@ -394,6 +426,7 @@ function tripal_get_vocabulary_root_terms($vocabulary) {
     }
   }
 }
+
 /**
  * Retrieves the immediate children of the given term.
  *
@@ -423,6 +456,7 @@ function tripal_get_term_children($vocabulary, $accession) {
     }
   }
 }
+
 /**
  * Retrieves full information about a vocabulary.
  *
@@ -477,6 +511,8 @@ function tripal_get_vocabulary_details($vocabulary) {
  * @param $element
  *   The pager element. This is equivalent to the element from the
  *   pager_default_initialize() function of Drupal.
+ * 
+ * @ingroup tripal_terms_api
  */
 function tripal_get_vocabulary_terms($vocabulary, $limit = 25, $element = 0) {
   $stores = module_invoke_all('vocab_storage_info');
@@ -497,6 +533,8 @@ function tripal_get_vocabulary_terms($vocabulary, $limit = 25, $element = 0) {
  *   An array of vocabularies where each entry in the array is compatible
  *   with the array returned by the tripal_get_vocabulary_details()
  *   function.
+ * 
+ * @ingroup tripal_terms_api
  */
 function tripal_get_vocabularies() {
   $stores = module_invoke_all('vocab_storage_info');
@@ -520,7 +558,7 @@ function tripal_get_vocabularies() {
  * multiple vocabularies and the user would need to select the proper term.
  *
  * This function will add the form elements necessary to provide a lookup form.
- * The form elements should work with a flat fortm (no #tree set for the form)
+ * The form elements should work with a flat form (no #tree set for the form)
  * or with a form in a TripalField.
  *
  * Use the tripal_get_term_lookup_form_result() function to retreive the
@@ -716,4 +754,4 @@ function tripal_get_term_lookup_form_ajax_callback($form, $form_state) {
   else {
     return $form['term_match'];
   }
-}
+}

tripal/api/tripal.upload.api.inc

@@ -90,7 +90,8 @@
  * file by querying for the file category for the current project.
  *
  * @code
- *   $seq_files = TripalFeature::getFilesByTypes($user->uid, array('sequence_file'), $project_id);
+ *   $seq_files = TripalFeature::getFilesByTypes($user->uid, 
+ *                   array('sequence_file'), $project_id);
  * @endcode
  *
  * 4) If the 'target_id' was used in array for step #2 above, then the
@@ -140,4 +141,4 @@ function hook_file_upload_check($action, $details, &$message){
       break;
   }
   return TRUE;
-}
+}

tripal_bulk_loader/api/tripal_bulk_loader.api.templates.inc

@@ -10,7 +10,8 @@
  * @defgroup tripal_bulk_loader_api Bulk Loader
  * @ingroup tripal_api
  * @{
- * All functions in this file provide an API to administrative management of bulk loader templates
+ * All functions in this file provide an API to administrative management of 
+ * bulk loader templates.
  * @}
  */
 
@@ -21,10 +22,10 @@
  *   The type of validation. Can be either 'insert' or 'update'.
  * @param $options
  *   An array of key/value pairs containing the following keys:
- *     'template_name':   The name of the template.
- *     'template_array':  The JSON array representing the template.
- *   Optional:
- *     'strict':          If set then only JSON formatted templates are allowed.
+ *     template_name: The name of the template.
+ *     template_array: The JSON array representing the template.
+ *     Optional:
+ *      strict: If set then only JSON formatted templates are allowed.
  * @param $errors
  *   An empty array where validation error messages will be set. The keys
  *   of the array will be name of the field from the options array and the
@@ -42,6 +43,7 @@
  *   the option and the value being the error message.  If validation
  *   is successful then TRUE is returned.
  *
+ *  @ingroup tripal_bulk_loader_api
  */
 function tripal_validate_bulk_loader_template($val_type, &$options, &$errors, &$warnings = array()) {
   $template_array = trim($options['template_array']);
@@ -105,7 +107,7 @@ function tripal_validate_bulk_loader_template($val_type, &$options, &$errors, &$
 /**
  * Inserts a bulk loader template record.
  *
- * This function validates the options passed prior to insertion of the record,
+ * This function validates the options passed prior to insertion of the record.
  *
  * @param $options
  *   An array of key/value pairs containing the following keys:
@@ -125,6 +127,8 @@ function tripal_validate_bulk_loader_template($val_type, &$options, &$errors, &$
  *   value is the error message.
  * @return
  *   TRUE for success and FALSE for failure.
+ * 
+ *  @ingroup tripal_bulk_loader_api
  */
 function tripal_insert_bulk_loader_template($options, &$errors, &$warnings) {
 
@@ -178,20 +182,23 @@ function tripal_insert_bulk_loader_template($options, &$errors, &$warnings) {
 }
 
 /**
- * Meant to be called from a form_validate function to ensure a newly added bulk loader record
- * name is unique and not empty.
+ * Meant to be called from a form_validate function to ensure a newly added bulk 
+ * loader record name is unique and not empty.
  *
  * @param $new_record_name
  *   The record name to check for uniqueness
  * @param $template_id
  *   The template_id of the template to add the record to
  * @param $template_array
- *   The array describing the template. Optional -will be loaded using template_id if not provided
+ *   The array describing the template. Optional -will be loaded using 
+ *   template_id if not provided
  * @param $current_priority
- *   The priority of the already existing record -checks that the name only occurs on this particular record
+ *   The priority of the already existing record -checks that the name only 
+ *   occurs on this particular record
  *
  * @return
- *   TRUE if the record name is not empty and not already in the template_array; FALSE otherwise
+ *   TRUE if the record name is not empty and not already in the template_array; 
+ *   FALSE otherwise
  *
  * @ingroup tripal_bulk_loader_api
  */

tripal_chado/api/generate_chado_schema_file.php

@@ -11,16 +11,16 @@
  *
  * @code
  *'chado' => array(
-    'default' => array(
-      'database' => 'd7x_t2x_c13',
-      'username' => 'chado',
-      'password' => 'testing123',
-      'host' => 'localhost',
-      'port' => '',
-      'driver' => 'pgsql',
-      'prefix' => '',
-    ),
-  ),
+ *   'default' => array(
+ *     'database' => 'd7x_t2x_c13',
+ *     'username' => 'chado',
+ *     'password' => 'testing123',
+ *     'host' => 'localhost',
+ *     'port' => '',
+ *     'driver' => 'pgsql',
+ *     'prefix' => '',
+ *   ),
+ * ),
  * @endcode
  *
  * This script requires a single argument (-v) which is the Chado version.

tripal_chado/api/modules/tripal_chado.analysis.api.inc

@@ -16,24 +16,26 @@
 
 
 /**
- * Retrieves an chado analysis variable
+ * Retrieves a chado analysis variable.
  *
  * @param $itentifier
- *   an array with the key stating what the identifier is. Supported keys (only on of the
- *   following unique keys is required):
- *    - analysis_id: the chado analysis.analysis_id primary key
- *    - nid: the drupal node.nid primary key
+ *   an array with the key stating what the identifier is. Supported keys 
+ *   (only on of the following unique keys is required):
+ *    - analysis_id: the chado analysis.analysis_id primary key.
+ *    - nid: the drupal node.nid primary key.
  *   There are also some specially handled keys. They are:
- *    - property: An array/object describing the property to select records for. It
- *      should at least have either a type_name (if unique across cvs) or type_id. Other
- *      supported keys include: cv_id/cv_name (of the type), value and rank
+ *    - property: An array/object describing the property to select records for. 
+ *      It should at least have either a type_name (if unique across cvs) or 
+ *      type_id. Other supported keys include: cv_id/cv_name (of the type), 
+ *      value and rank.
  * @param $options
  *   An array of options. Supported keys include:
- *     - Any keys supported by chado_generate_var(). See that function definition for
- *       additional details.
+ *     - Any keys supported by chado_generate_var(). See that function 
+ *       definition for additional details.
  *
- * NOTE: the $identifier parameter can really be any array similar to $values passed into
- *   chado_select_record(). It should fully specify the stock record to be returned.
+ * NOTE: the $identifier parameter can really be any array similar to $values 
+ * passed into chado_select_record(). It should fully specify the stock record 
+ * to be returned.
  *
  * @return
  *   the analysis node matching the passed in identifier
@@ -44,11 +46,11 @@ function tripal_get_analysis($identifier, $options) {
 
   // Set Defaults
   if (!isset($options['include_fk'])) {
-    // Tells chado_generate_var not to follow any foreign keys
+    // Tells chado_generate_var not to follow any foreign keys.
     $options['include_fk'] = array();
   }
 
-  // Error Checking of parameters
+  // Error Checking of parameters.
   if (!is_array($identifiers)) {
     tripal_report_error(
       'tripal_stock_api',
@@ -73,7 +75,7 @@ function tripal_get_analysis($identifier, $options) {
     );
   }
 
-  // If one of the identifiers is property then use chado_get_record_with_property()
+  // If one of the identifiers is property then use chado_get_record_with_property().
   if (isset($identifiers['property'])) {
     $property = $identifiers['property'];
     unset($identifiers['property']);
@@ -83,7 +85,8 @@ function tripal_get_analysis($identifier, $options) {
     );
   }
 
-  // Else we have a simple case and we can just use chado_generate_var to get the analysis
+  // Else we have a simple case and we can just use chado_generate_var to get 
+  // the analysis.
   else {
 
     // Try to get the analysis
@@ -94,7 +97,7 @@ function tripal_get_analysis($identifier, $options) {
     );
   }
 
-  // Ensure the analysis is singular. If it's an array then it is not singular
+  // Ensure the analysis is singular. If it's an array then it is not singular.
   if (is_array($analysis)) {
     tripal_report_error(
       'tripal_analysis_api',
@@ -106,7 +109,8 @@ function tripal_get_analysis($identifier, $options) {
     );
   }
 
-  // Report an error if $analysis is FALSE since then chado_generate_var has failed
+  // Report an error if $analysis is FALSE since then chado_generate_var has 
+  // failed.
   elseif ($analysis === FALSE) {
     tripal_report_error(
       'tripal_analysis_api',
@@ -126,14 +130,15 @@ function tripal_get_analysis($identifier, $options) {
   }
 }
 /**
- * Returns a list of analyses that are currently synced with Drupal to use in select lists
+ * Returns a list of analyses that are currently synced with Drupal to use in 
+ * select lists.
  *
  * @param $syncd_only
- *   Whether or not to return all chado analyses or just those sync'd with drupal. Defaults
- *   to TRUE (only sync'd analyses)
+ *   Whether or not to return all chado analyses or just those sync'd with 
+ *   drupal. Defaults to TRUE (only sync'd analyses).
  * @return
- *   An array of analyses sync'd with Drupal where each value is the analysis scientific
- *   name and the keys are analysis_id's
+ *   An array of analyses sync'd with Drupal where each value is the analysis 
+ *   scientific name and the keys are analysis_id's.
  *
  * @ingroup tripal_analysis_api
  */
@@ -150,7 +155,7 @@ function tripal_get_analysis_select_options($syncd_only = TRUE) {
     ";
     $analyses = chado_query($sql);
 
-    // iterate through the analyses and build an array of those that are synced
+    // iterate through the analyses and build an array of those that are synced.
     foreach ($analyses as $analysis) {
       $analysis_list[$analysis->analysis_id] = $analysis->name;
     }
@@ -160,7 +165,7 @@ function tripal_get_analysis_select_options($syncd_only = TRUE) {
     $csql =  "SELECT * FROM {analysis} ORDER BY name";
     $analyses = chado_query($csql);
 
-    // iterate through the analyses and build an array of those that are synced
+    // iterate through the analyses and build an array of those that are synced.
     foreach ($analyses as $analysis) {
       $analysis_list[$analysis->analysis_id] = $analysis->name;
     }

tripal_chado/api/modules/tripal_chado.contact.api.inc

@@ -14,21 +14,22 @@
  */
 
 /**
- * Adds a contact to the Chado contact table
+ * Adds a contact to the Chado contact table.
  *
  * @param $values
  *   An array of values to be inserted. Valid keys include:
- *   - name: The name of the contact
- *   - description: Text describing the contact
- *   - type_name: The type of contact.  Must be a term in the tripal_contact vocabulary
- *   - properties: An associative array containing a list of key value pairs for the properites.
- *     The key's must be valid terms in the tripal_contact vocabulary (e.g. Affiliation,
- *     Address, etc).
+ *   - name: The name of the contact.
+ *   - description: Text describing the contact.
+ *   - type_name: The type of contact.  Must be a term in the tripal_contact 
+ *     vocabulary.
+ *   - properties: An associative array containing a list of key value pairs for
+ *     the properites. The key's must be valid terms in the tripal_contact 
+ *     vocabulary (e.g. Affiliation, Address, etc).
  *
  * @return
  *   On success, an array is returned containing the fields of the contact
  *   record including the newly added contact_id. On failure, FALSE is
- *   returned
+ *   returned.
  *
  * @ingroup tripal_contact_api
  */
@@ -115,10 +116,10 @@ function tripal_insert_contact($values) {
  * This function is intended to be used in autocomplete forms for contacts.
  *
  * @param $text
- *   The string to search for
+ *   The string to search for.
  *
  * @return
- *   A json array of terms that begin with the provided string
+ *   A json array of terms that begin with the provided string.
  *
  * @ingroup tripal_contact_api
  */

tripal_chado/api/modules/tripal_chado.cv.api.inc

@@ -18,34 +18,35 @@
  * Retrieves a chado controlled vocabulary variable
  *
  * @param $identifier
- *   An array with the key stating what the identifier is. Supported keys (only on of the
- *   following unique keys is required):
- *    - cv_id: the chado cv.cv_id primary key
- *    - name: the chado cv.name field (assume unique)
+ *   An array with the key stating what the identifier is. Supported keys (only 
+ *   on of the following unique keys is required):
+ *    - cv_id: the chado cv.cv_id primary key.
+ *    - name: the chado cv.name field (assume unique).
  * @param $options
  *   An array of options. Supported keys include:
- *     - Any keys supported by chado_generate_var(). See that function definition for
- *       additional details.
+ *     - Any keys supported by chado_generate_var(). See that function 
+ *       definition fot additional details.
  *
- * NOTE: the $identifier parameter can really be any array similar to $values passed into
- *   chado_select_record(). It should fully specify the cv record to be returned.
+ * NOTE: the $identifier parameter can really be any array similar to $values 
+ * passed into chado_select_record(). It should fully specify the cv record to 
+ * be returned.
  *
  * @return
- *   If unique values were passed in as an identifier then an object describing the cv
- *   will be returned (will be a chado variable from chado_generate_var()). Otherwise,
- *   FALSE will be returned.
+ *   If unique values were passed in as an identifier then an object describing 
+ *   the cv will be returned (will be a chado variable from 
+ *   chado_generate_var()). Otherwise, FALSE will be returned.
  *
  * @ingroup tripal_chado_cv_api
  */
 function tripal_get_cv($identifiers, $options = array()) {
 
-  // Set Defaults
+  // Set Defaults.
   if (!isset($options['include_fk'])) {
-    // Tells chado_generate_var not to follow any foreign keys
+    // Tells chado_generate_var not to follow any foreign keys.
     $options['include_fk'] = array();
   }
 
-  // Error Checking of parameters
+  // Error Checking of parameters.
   if (!is_array($identifiers)) {
     tripal_report_error(
       'tripal_chado_api',
@@ -70,14 +71,14 @@ function tripal_get_cv($identifiers, $options = array()) {
     );
   }
 
-  // Try to get the cv
+  // Try to get the cv.
   $cv = chado_generate_var(
     'cv',
     $identifiers,
     $options
   );
 
-  // Ensure the cv is singular. If it's an array then it is not singular
+  // Ensure the cv is singular. If it's an array then it is not singular.
   if (is_array($cv)) {
     tripal_report_error(
       'tripal_chado_api',
@@ -89,7 +90,7 @@ function tripal_get_cv($identifiers, $options = array()) {
     );
   }
 
-  // Report an error if $cv is FALSE since then chado_generate_var has failed
+  // Report an error if $cv is FALSE since then chado_generate_var has failed.
   elseif ($cv === FALSE) {
     tripal_report_error(
       'tripal_chado_api',
@@ -111,10 +112,10 @@ function tripal_get_cv($identifiers, $options = array()) {
 
 /**
  * Create an options array to be used in a form element which provides a
- * list of all chado cvs
+ * list of all chado cvs.
  *
  * @return
- *   An array(cv_id => name) for each cv in the chado cv table
+ *   An array(cv_id => name) for each cv in the chado cv table.
  *
  * @ingroup tripal_chado_cv_api
  */
@@ -134,7 +135,7 @@ function tripal_get_cv_select_options() {
 }
 
 /**
- * Retrieves a chado controlled vocabulary term variable
+ * Retrieves a chado controlled vocabulary term variable.
  *
  * @param $identifier
  *   An array apropriate for use with the chado_generate_var for uniquely
@@ -146,11 +147,11 @@ function tripal_get_cv_select_options() {
  *      name of the cv.
  *    - synonym: an array with 'name' => the name of the synonym of the cvterm
  *      you want returned; 'cv_id' => the cv_id of the synonym; 'cv_name' =>
- *      the name of the cv of the synonym
+ *      the name of the cv of the synonym.
  *    - property: An array/object describing the property to select records
  *      for. It should at least have either a type_name (if unique across cvs)
  *      or type_id. Other supported keys include: cv_id/cv_name (of the type),
- *      value and rank
+ *      value and rank.
  * @param $options
  *   An array of options. Supported keys include:
  *     - Any keys supported by chado_generate_var(). See that function
@@ -169,13 +170,13 @@ function tripal_get_cv_select_options() {
  */
 function tripal_get_cvterm($identifiers, $options = array()) {
 
-  // Set Defaults
+  // Set Defaults.
   if (!isset($options['include_fk'])) {
-    // Tells chado_generate_var to only get the cv
+    // Tells chado_generate_var to only get the cv.
     $options['include_fk'] = array('cv_id' => TRUE);
   }
 
-  // Error Checking of parameters
+  // Error Checking of parameters.
   if (!is_array($identifiers)) {
     tripal_report_error('tripal_cv_api', TRIPAL_ERROR,
       "tripal_get_cvterm: The identifier passed in is expected to be an array with the key
@@ -192,7 +193,8 @@ function tripal_get_cvterm($identifiers, $options = array()) {
     );
   }
 
-  // If synonym was passed in, then process this first before calling chado_generate_var()
+  // If synonym was passed in, then process this first before calling 
+  // chado_generate_var().
   if (isset($identifiers['synonym'])) {
     $synonym = $identifiers['synonym']['name'];
 
@@ -208,7 +210,8 @@ function tripal_get_cvterm($identifiers, $options = array()) {
     );
     $result = chado_select_record('cvtermsynonym', array('cvterm_id'), $values, $options);
 
-    // if the synonym doens't exist or more than one record is returned then return false
+    // if the synonym doens't exist or more than one record is returned then 
+    // return false.
     if (count($result) == 0) {
       return FALSE;
     }
@@ -219,7 +222,7 @@ function tripal_get_cvterm($identifiers, $options = array()) {
     $identifiers = array('cvterm_id' => $result[0]->cvterm_id);
   }
 
-  // If one of the identifiers is property then use chado_get_record_with_property()
+  // If one of the identifiers is property then use chado_get_record_with_property().
   if (isset($identifiers['property'])) {
     $property = $identifiers['property'];
     unset($identifiers['property']);
@@ -241,13 +244,14 @@ function tripal_get_cvterm($identifiers, $options = array()) {
     ));
   }
 
-  // Else we have a simple case and we can just use chado_generate_var to get the cvterm
+  // Else we have a simple case and we can just use chado_generate_var to get 
+  // the cvterm.
   else {
-    // Try to get the cvterm
+    // Try to get the cvterm.
     $cvterm = chado_generate_var('cvterm', $identifiers, $options);
   }
 
-  // Ensure the cvterm is singular. If it's an array then it is not singular
+  // Ensure the cvterm is singular. If it's an array then it is not singular.
   if (is_array($cvterm)) {
     tripal_report_error(
       'tripal_cv_api',
@@ -259,7 +263,8 @@ function tripal_get_cvterm($identifiers, $options = array()) {
     );
   }
 
-  // Report an error if $cvterm is FALSE since then chado_generate_var has failed
+  // Report an error if $cvterm is FALSE since then chado_generate_var has 
+  // failed.
   elseif ($cvterm === FALSE) {
     tripal_report_error(
       'tripal_cv_api',
@@ -282,10 +287,10 @@ function tripal_get_cvterm($identifiers, $options = array()) {
 
 /**
  * Create an options array to be used in a form element
- *   which provides a list of all chado cvterms
+ *   which provides a list of all chado cvterms.
  *
  * @param $cv_id
- *   The chado cv_id; only cvterms with the supplied cv_id will be returned
+ *   The chado cv_id; only cvterms with the supplied cv_id will be returnedl.
  * @param $rel_type
  *   Set to TRUE if the terms returned should only be relationship types in
  *   the vocabulary.  This is useful for creating drop-downs of terms
@@ -293,7 +298,7 @@ function tripal_get_cvterm($identifiers, $options = array()) {
  *
  * @return
  *   An associative array with the cvterm_id's as keys. The first
- *   element in the array has a key of '0' and a value of 'Select a Type'
+ *   element in the array has a key of '0' and a value of 'Select a Type'.
  *
  * @ingroup tripal_chado_cv_api
  */
@@ -321,20 +326,20 @@ function tripal_get_cvterm_select_options($cv_id, $rel_type = FALSE) {
  * Updates the cvtermpath table of Chado for the specified CV.
  *
  * @param $cv_id
- *   The chado cv_id;
+ *   The chado cv_id.
  * @param $job_id
  *   This function is intended to be used with the Tripal Jobs API.
  *   When this function is called as a job the $job_id is automatically
  *   passed to this function.
  * @return
- *   TRUE on success FALSE on failure
+ *   TRUE on success FALSE on failure.
  *
  * @ingroup tripal_chado_cv_api
  */
 function tripal_update_cvtermpath_old($cv_id, $job_id = NULL) {
   // TODO: need better error checking in this function
 
-  // first get the controlled vocabulary name:
+  // First get the controlled vocabulary name:
   $sql = "SELECT * FROM {cv} WHERE cv_id = :cv_id";
   $cv = chado_query($sql, array(':cv_id' => $cv_id))->fetchObject();
 
@@ -417,13 +422,6 @@ function tripal_update_cvtermpath($cv_id, $job_id = NULL){
  * @ingroup tripal_chado_cv_api
  */
 function tripal_update_cvtermpath_root_loop($rootid, $cvid, &$roots) {
-  // Get's the cvterm record for this "root".
-  // $ttype = db_select('cvterm', 'cv')
-  //         ->fields('cv', array('cvterm_id'));
-  // $db_or = db_or();
-  // $db_or->condition('cv.name', "isa", '=');
-  // $db_or->condition('cv.name', "is_a", '=');
-  // $ttype->condition($db_or);
   $ttype = db_query(
     'SELECT cv.cvterm_id 
     FROM cvterm cv
@@ -481,7 +479,7 @@ function tripal_update_cvtermpath_root_loop($rootid, $cvid, &$roots) {
  * @param $depth
  *   The depth of the recursion.
  * @param $increment_of_depth.
- *   An integer ??
+ *   An integer tailing the number of children that have been walked down.
  * @param $tree_path.
  *   The array of every term between the current child and the origin. Each
  *   element in the array is an associative array with the keys:
@@ -494,8 +492,8 @@ function tripal_update_cvtermpath_root_loop($rootid, $cvid, &$roots) {
  *    An array of rows that are currently in the cvtermpath table that match the
  *    build_id of the current term trying to be written to the table
  * @param $possible_start_of_ loop
- *    The array of the possible loop item between the current child and the origin.
- *    Each element in the array is an associative array with the keys:
+ *    The array of the possible loop item between the current child and the 
+ *    origin. Each element in the array is an associative array with the keys:
  *     - cvid : $cv_id
  *     - subject_id:
  *     - child_id : $child_id,
@@ -503,7 +501,9 @@ function tripal_update_cvtermpath_root_loop($rootid, $cvid, &$roots) {
  *     - depth : $depth,
  * @param $no_loop_skip_test
  *     A boolean used when the possible loop has been ruled out as a loop.
- * @return multitype:
+ * 
+ * 
+ * @ingroup tripal_chado_cv_api
  */
 function tripal_update_cvtermpath_loop(
   $origin,
@@ -637,7 +637,7 @@ function tripal_update_cvtermpath_loop(
  * @param $depth
  *   The depth of the recursion.
  * @param $increment_of_depth.
- *   An integer ??
+ *   An integer.
  * @param $tree_path.
  *   The array of every term between the current child and the origin. Each
  *   element in the array is an associative array with the keys:
@@ -659,7 +659,10 @@ function tripal_update_cvtermpath_loop(
  *     - depth : $depth,
  * @param $no_loop_skip_test
  *     A boolean used when the possible loop has been ruled out as a loop.
- * @return multitype:
+ * @return multitype: Either a number that represents the row count of existing 
+ * rows that already match these specification or a Boolean false.
+ * 
+ * @ingroup tripal_chado_cv_api
  */
 function tripal_update_cvtermpath_loop_increment(
   $origin,
@@ -701,17 +704,19 @@ function tripal_update_cvtermpath_loop_increment(
     $term_id = $origin . '|' . $child_id . '|' . $cv_id . '|' . $type_id;
 
     if ($no_loop_skip_test === FALSE) {
-      // If the increment of depth is 0 then it's the first time and we need to skip
-      // the test so we can build the tree_path which will be tested against.
+      // If the increment of depth is 0 then it's the first time and we need to 
+      // skip the test so we can build the tree_path which will be tested against.
       if ($increment_of_depth != 0) {
         // Search the $tree_path for the new $child_id in the build_id column.
         foreach ($tree_path as $parent) {
           // If this child is the same as a parent term that has already been
           // processed then we have a potential loop.
           if ($parent['build_id'] == $term_id) {
-            // Tell the function this is a possible loop and to stop writing to the table.
+            // Tell the function this is a possible loop and to stop writing to 
+            // the table.
             $possible_loop = TRUE;
-            // Find all the results in the table that might be the start of the loop.
+            // Find all the results in the table that might be the start of the 
+            // loop.
             $matching_rows = db_query(
               ' SELECT *
                 FROM cvtermpath
@@ -753,7 +758,7 @@ function tripal_update_cvtermpath_loop_increment(
       } catch (Exception $e) {
         $error = $e->getMessage();
         tripal_report_error('tripal_chado', TRIPAL_ERROR, "Could not fill cvtermpath term: @error", array('@error' => $error));
-        return false;
+        return FALSE;
       }
 
       // Then add that new entry to the $tree_path.
@@ -806,7 +811,7 @@ function tripal_update_cvtermpath_loop_increment(
 }
 
 /**
- * Adds a controlled vocabular to the CV table of Chado.
+ * Adds a controlled vocabulary to the CV table of Chado.
  *
  * @param $name
  *   The name of the controlled vocabulary. These are typically all lower case
@@ -821,17 +826,17 @@ function tripal_update_cvtermpath_loop_increment(
  */
 function tripal_insert_cv($name, $definition) {
 
-  // insert/update values
+  // Insert/update values.
   $ins_values = array(
     'name'       => $name,
     'definition' => $definition
   );
 
-  // see if the CV default exists already in the database
+  // See if the CV default exists already in the database.
   $sel_values = array('name' => $name);
   $results = chado_select_record('cv', array('*'), $sel_values);
 
-  // if it does not exists then add it
+  // If it does not exists then add it.
   if (count($results) == 0) {
     $success = chado_insert_record('cv', $ins_values);
     if (!$success) {
@@ -840,7 +845,7 @@ function tripal_insert_cv($name, $definition) {
     }
     $results = chado_select_record('cv', array('*'), $sel_values);
   }
-  // if it already exists then do an update
+  // If it already exists then do an update.
   else {
     $success = chado_update_record('cv', $sel_values, $ins_values);
     if (!$success) {
@@ -850,7 +855,7 @@ function tripal_insert_cv($name, $definition) {
     $results = chado_select_record('cv', array('*'), $sel_values);
   }
 
-  // return the cv object
+  // Return the cv object.
   return $results[0];
 }
 
@@ -875,13 +880,13 @@ function tripal_insert_cv($name, $definition) {
  *      <DB> is the name of the database to which the cvterm belongs and the
  *      <ACCESSION> is the term's accession number in the database.
  *    - name: the name of the term. usually meant to be human-readable.
- *    - is_obsolete: is present and set to 1 if the term is defunct
- *    - definition: the definition of the term
+ *    - is_obsolete: is present and set to 1 if the term is defunct.
+ *    - definition: the definition of the term.
  *    - cv_name: The CV name to which the term belongs.  If this arugment is
  *        null or not provided then the function tries to find a record in the
  *        CV table with the same name provided in the $term[namespace].  If
  *        this field is provided then it overrides what the value in
- *        $term[namespace]
+ *        $term[namespace].
  *    - is_relationship: If this term is a relationship term then this value
  *        should be 1.
  *    - db_name: In some cases the database name will not be part of the
@@ -900,7 +905,7 @@ function tripal_insert_cv($name, $definition) {
  */
 function tripal_insert_cvterm($term, $options = array()) {
 
-  // get the term properties
+  // Get the term properties.
   $id = (isset($term['id'])) ? $term['id'] : '';
   $name = '';
   $cvname = '';
@@ -908,7 +913,7 @@ function tripal_insert_cvterm($term, $options = array()) {
   $is_obsolete = 0;
   $accession = '';
 
-  // Set Defaults
+  // Set Defaults.
   if (isset($term['cv_name'])) {
     $cvname = $term['cv_name'];
   }
@@ -916,7 +921,7 @@ function tripal_insert_cvterm($term, $options = array()) {
     $cvname = 'local';
   }
   // Namespace is deprecated but must be supported for backwards
-  // compatability
+  // compatability.
   if (array_key_exists('namespace', $term)) {
     $cvname = $term['namespace'];
   }
@@ -991,7 +996,7 @@ function tripal_insert_cvterm($term, $options = array()) {
     return 0;
   }
 
-  // Make sure the CV name exists
+  // Make sure the CV name exists.
   $cv = tripal_get_cv(array('name' => $cvname));
   if (!$cv) {
     $cv = tripal_insert_cv($cvname, '');
@@ -1128,7 +1133,7 @@ function tripal_insert_cvterm($term, $options = array()) {
           return 0;
         }
       }
-      // get the original cvterm with the same name and return that.
+      // Get the original cvterm with the same name and return that.
       $result = chado_query($cvtermsql, array(':accession' => $dbxref->accession, ':name' => $dbname));
       $cvterm = $result->fetchObject();
       return $cvterm;
@@ -1137,7 +1142,7 @@ function tripal_insert_cvterm($term, $options = array()) {
     // We can now perform and updated if we need to.
   }
 
-  // get the CVterm record
+  // Get the CVterm record.
   $result = chado_query($cvtermsql, array(':accession' => $accession, ':name' => $dbname));
   $cvterm = $result->fetchObject();
   if (!$cvterm) {
@@ -1203,7 +1208,8 @@ function tripal_insert_cvterm($term, $options = array()) {
       return 0;
     }
 
-    // Second, check that the dbxref has not changed and if it has then update it.
+    // Second, check that the dbxref has not changed and if it has then update 
+    // it.
     $checksql = "
       SELECT cvterm_id
       FROM {cvterm} CVT
@@ -1215,7 +1221,7 @@ function tripal_insert_cvterm($term, $options = array()) {
     $check = chado_query($checksql, array(':accession' => $accession, ':dbname' => $dbname, ':term' => $name, ':cvname' => $cvname))->fetchObject();
     if (!$check) {
 
-      // check to see if the dbxref exists if not, add it.
+      // Check to see if the dbxref exists if not, add it.
       $dbxref =  tripal_insert_dbxref(array(
         'db_id' => $db->db_id,
         'accession' => $accession
@@ -1242,9 +1248,9 @@ function tripal_insert_cvterm($term, $options = array()) {
     $cvterm = $result->fetchObject();
   }
   else {
-    // do nothing, we have the cvterm but we don't want to update
+    // Do nothing, we have the cvterm but we don't want to update.
   }
-  // return the cvterm
+  // Return the cvterm.
   return $cvterm;
 }
 
@@ -1252,6 +1258,8 @@ function tripal_insert_cvterm($term, $options = array()) {
 /**
  * TODO: deprecate this function
  *
+ * Avoid using this function as it will be deprecated in future releases.
+ * 
  * This function allows other modules to programatically
  * submit an ontology for loading into Chado.
  *
@@ -1266,7 +1274,7 @@ function tripal_insert_cvterm($term, $options = array()) {
  * @param $obo_id
  *   If the ontology is already loaded into the Tripal tables then
  *   use this argument to specify the unique ID for the ontology
- *   that will be loaded
+ *   that will be loaded.
  * @param $obo_name
  *   If the OBO has not been added before then use this argument
  *   to specify the human readable name of the ontology.
@@ -1330,17 +1338,17 @@ function tripal_submit_obo_job($obo) {
  * If the OBO name already exists in the table then the path is updated.
  *
  * @param $name
- *   The human readable name of this ontology
+ *   The human readable name of this ontology.
  * @param $path
- *   The file path or URL of the ontology
+ *   The file path or URL of the ontology.
  *
  * @return
- *   Returns the ontology ID
+ *   Returns the ontology ID.
  *
  * @ingroup tripal_chado_api
  */
 function tripal_insert_obo($name, $path) {
-  // make sure an OBO with the same name doesn't already exist
+  // Make sure an OBO with the same name doesn't already exist.
   $obo_id = db_select('tripal_cv_obo', 'tco')
     ->fields('tco', array('obo_id'))
     ->condition('name', $name)
@@ -1371,7 +1379,7 @@ function tripal_insert_obo($name, $path) {
  * Retrieves an OBO record.
  *
  * @param $values
- *   An associate array with the following allowed keys: obo_id, name
+ *   An associate array with the following allowed keys: obo_id, name.
  *
  * @return
  *   An instance of an OBO record object.
@@ -1388,16 +1396,17 @@ function tripal_get_obo($values) {
   }
   return $query->execute()->fetchObject();
 }
+
 /**
  * This function is intended to be used in autocomplete forms.
  *
  * This function searches for a matching controlled vobulary name.
  *
  * @param $string
- * The string to search for
+ * The string to search for.
  *
  * @return
- * A json array of terms that begin with the provided string
+ * A json array of terms that begin with the provided string.
  *
  * @ingroup tripal_chado_api
  */
@@ -1417,17 +1426,18 @@ function tripal_autocomplete_cv($string = '') {
 
   drupal_json_output($items);
 }
+
 /**
  * This function is intended to be used in autocomplete forms
- * for searching for CV terms that begin with the provided string
+ * for searching for CV terms that begin with the provided string.
  *
  * @param $cv_id
- * The CV ID in which to search for the term
+ * The CV ID in which to search for the term.
  * @param $string
- * The string to search for
+ * The string to search for.
  *
  * @return
- * A json array of terms that begin with the provided string
+ * A json array of terms that begin with the provided string.
  *
  * @ingroup tripal_chado_api
  */
@@ -1479,13 +1489,15 @@ function tripal_autocomplete_cvterm($cv_id, $string = '') {
 }
 
 /**
- * Add a record to a cvterm linking table (ie: feature_cvterm)
+ * Add a record to a cvterm linking table (ie: feature_cvterm).
  *
  * @param $basetable
- *   The base table to which the cvterm should be linked/associated. Thus to associate a
- *   cvterm to a feature the basetable=feature and cvterm_id is added to the feature_cvterm table.
+ *   The base table to which the cvterm should be linked/associated. Thus to 
+ *   associate a cvterm to a feature the basetable=feature and cvterm_id is
+ *   added to the feature_cvterm table.
  * @param $record_id
- *   The primary key of the basetable to associate the cvterm with. This should be in integer.
+ *   The primary key of the basetable to associate the cvterm with. This should 
+ *   be in integer.
  * @param $cvterm
  *   An associative array describing the cvterm. Valid keys include:
  *     - name: the name for the cvterm,
@@ -1493,7 +1505,8 @@ function tripal_autocomplete_cvterm($cv_id, $string = '') {
  *     - cv_id: the primary key of the cv the cvterm belongs to.
  * @param $options
  *   An associative array of options. Valid keys include:
- *     - insert_cvterm: Insert the cvterm if it doesn't already exist. FALSE is the default
+ *     - insert_cvterm: Insert the cvterm if it doesn't already exist. FALSE is 
+ *       the default.
  *
  * @ingroup tripal_chado_api
  */
@@ -1504,7 +1517,8 @@ function tripal_associate_cvterm($basetable, $record_id, $cvterm, $options = arr
   // Default Values
   $options['insert_cvterm'] = (isset($options['insert_cvterm'])) ? $options['insert_cvterm'] : FALSE;
 
-  // If the cvterm_id is not set then find the cvterm record using the name and cv_id
+  // If the cvterm_id is not set then find the cvterm record using the name and 
+  // cv_id.
   if (!isset($cvterm['cvterm_id'])) {
     $values = array(
       'name' => $cvterm['name'],
@@ -1556,7 +1570,7 @@ function tripal_associate_cvterm($basetable, $record_id, $cvterm, $options = arr
     }
   }
 
-  // Now add the link between the record & cvterm
+  // Now add the link between the record & cvterm.
   if ($cvterm['cvterm_id'] > 0) {
     $values = array(
       'cvterm_id' => $cvterm['cvterm_id'],
@@ -1588,5 +1602,3 @@ function tripal_associate_cvterm($basetable, $record_id, $cvterm, $options = arr
 
   return FALSE;
 }
-
-

tripal_chado/api/modules/tripal_chado.db.api.inc

@@ -13,55 +13,56 @@
  */
 
 /**
- * Retrieves a chado db variable
+ * Retrieves a chado db variable.
  *
  * Example Usage:
  * @code
-    $select_values = array(
-      'name' => 'SOFP'
-    );
-    $db_object = tripal_get_db($select_values);
+ *   $select_values = array(
+ *     'name' => 'SOFP'
+ *   );
+ *   $db_object = tripal_get_db($select_values);
  * @endcode
  *  The above code selects the SOFP db and returns the following object:
  * @code
-    $db_object = stdClass Object (
-      [db_id] => 49
-      [name] => SOFP
-      [description] =>
-      [urlprefix] =>
-      [url] =>
-    );
+ *   $db_object = stdClass Object (
+ *     [db_id] => 49
+ *     [name] => SOFP
+ *     [description] =>
+ *     [urlprefix] =>
+ *     [url] =>
+ *   );
  * @endcode
  *
  * @param $identifier
- *   An array with the key stating what the identifier is. Supported keys (only on of the
- *   following unique keys is required):
- *    - db_id: the chado db.db_id primary key
- *    - name: the chado db.name field (assume unique)
+ *   An array with the key stating what the identifier is. Supported keys (only 
+ *   on of the following unique keys is required):
+ *    - db_id: the chado db.db_id primary key.
+ *    - name: the chado db.name field (assume unique).
  * @param $options
  *   An array of options. Supported keys include:
- *     - Any keys supported by chado_generate_var(). See that function definition for
- *       additional details.
+ *     - Any keys supported by chado_generate_var(). See that function 
+ *       definition for additional details.
  *
- * NOTE: the $identifier parameter can really be any array similar to $values passed into
- *   chado_select_record(). It should fully specify the db record to be returned.
+ * NOTE: the $identifier parameter can really be any array similar to $values 
+ * passed into chado_select_record(). It should fully specify the db record to 
+ * be returned.
  *
  * @return
- *   If unique values were passed in as an identifier then an object describing the cv
- *   will be returned (will be a chado variable from chado_generate_var()). Otherwise,
- *   an array of objects will be returned.
+ *   If unique values were passed in as an identifier then an object describing 
+ *   the cv will be returned (will be a chado variable from 
+ *   chado_generate_var()). Otherwise, an array of objects will be returned.
  *
  * @ingroup tripal_chado_database_api
  */
 function tripal_get_db($identifiers, $options = array()) {
 
-  // Set Defaults
+  // Set Defaults.
   if (!isset($options['include_fk'])) {
-    // Tells chado_generate_var not to follow any foreign keys
+    // Tells chado_generate_var not to follow any foreign keys.
     $options['include_fk'] = array();
   }
 
-  // Error Checking of parameters
+  // Error Checking of parameters.
   if (!is_array($identifiers)) {
     tripal_report_error(
       'tripal_chado_database_api',
@@ -86,14 +87,14 @@ function tripal_get_db($identifiers, $options = array()) {
     );
   }
 
-  // Try to get the db
+  // Try to get the db.
   $db = chado_generate_var(
     'db',
     $identifiers,
     $options
   );
 
-  // Ensure the db is singular. If it's an array then it is not singular
+  // Ensure the db is singular. If it's an array then it is not singular.
   if (is_array($db)) {
     tripal_report_error(
       'tripal_chado_database_api',
@@ -105,7 +106,7 @@ function tripal_get_db($identifiers, $options = array()) {
     );
   }
 
-  // Report an error if $db is FALSE since then chado_generate_var has failed
+  // Report an error if $db is FALSE since then chado_generate_var has failed.
   elseif ($db === FALSE) {
     tripal_report_error(
       'tripal_chado_database_api',
@@ -127,10 +128,10 @@ function tripal_get_db($identifiers, $options = array()) {
 
 /**
  * Create an options array to be used in a form element
- *   which provides a list of all chado dbs
+ *   which provides a list of all chado dbs.
  *
  * @return
- *   An array(db_id => name) for each db in the chado db table
+ *   An array(db_id => name) for each db in the chado db table.
  *
  * @ingroup tripal_chado_database_api
  */
@@ -150,64 +151,67 @@ function tripal_get_db_select_options() {
 }
 
 /**
- * Retrieves a chado database reference variable
+ * Retrieves a chado database reference variable.
  *
  * Example Usage:
  * @code
-    $identifiers = array(
-      'accession' => 'synonym',
-      'db_id' => array(
-        'name' => 'SOFP'
-      )
-    );
-    $dbxref_object = tripal_get_dbxref($identifiers);
+ *   $identifiers = array(
+ *     'accession' => 'synonym',
+ *     'db_id' => array(
+ *       'name' => 'SOFP'
+ *     )
+ *   );
+ *   $dbxref_object = tripal_get_dbxref($identifiers);
  * @endcode
- *  The above code selects the synonym database reference and returns the following object:
+ *  The above code selects the synonym database reference and returns the 
+ *  following object:
  * @code
-    $dbxref_object = stdClass Object (
-      [dbxref_id] => 2581
-      [accession] => synonym
-      [description] =>
-      [version] =>
-      [db_db_id] => 49
-      [db_name] => SOFP
-      [db_description] =>
-      [db_urlprefix] =>
-      [db_url] =>
-    );
+ *  $dbxref_object = stdClass Object (
+ *     [dbxref_id] => 2581
+ *     [accession] => synonym
+ *     [description] =>
+ *     [version] =>
+ *     [db_db_id] => 49
+ *     [db_name] => SOFP
+ *     [db_description] =>
+ *     [db_urlprefix] =>
+ *     [db_url] =>
+ *   );
  * @endcode
  *
  * @param $identifier
  *   An array apropriate for use with the chado_generate_var for uniquely
  *   identifying a dbxref record. Alternatively, there are also some specially
  *   handled keys. They are:
- *    - property: An array/object describing the property to select records for. It
- *      should at least have either a type_name (if unique across cvs) or type_id. Other
- *      supported keys include: cv_id/cv_name (of the type), value and rank
+ *    - property: An array/object describing the property to select records for. 
+ *      It should at least have either a type_name (if unique across cvs) or 
+ *      type_id. Other supported keys include: cv_id/cv_name (of the type), 
+ *      value and rank.
  * @param $options
  *   An array of options. Supported keys include:
- *     - Any keys supported by chado_generate_var(). See that function definition for
- *       additional details.
+ *     - Any keys supported by chado_generate_var(). See that function 
+ *       definition for additional details.
  *
- * NOTE: the $identifier parameter can really be any array similar to $values passed into
- *   chado_select_record(). It should fully specify the dbxref record to be returned.
+ * NOTE: the $identifier parameter can really be any array similar to $values 
+ * passed into chado_select_record(). It should fully specify the dbxref record 
+ * to be returned.
  *
  * @return
- *   If unique values were passed in as an identifier then an object describing the dbxref
- *   will be returned (will be a chado variable from chado_generate_var()). Otherwise,
- *   FALSE will be returned.
+ *   If unique values were passed in as an identifier then an object describing 
+ *   the dbxref will be returned (will be a chado variable from 
+ *   chado_generate_var()). Otherwise, FALSE will be returned.
  *
- * @ingroup tripal_db_api
+ * @ingroup tripal_chado_database_api
  */
 function tripal_get_dbxref($identifiers, $options = array()) {
 
-  // Set Defaults
+  // Set Defaults.
   if (!isset($options['include_fk'])) {
-    // Tells chado_generate_var not only expand the db
+    // Tells chado_generate_var not only expand the db.
     $options['include_fk'] = array('db_id' => TRUE);
   }
 
-  // Error Checking of parameters
+  // Error Checking of parameters.
   if (!is_array($identifiers)) {
     tripal_report_error('tripal_db_api', TRIPAL_ERROR,
       "tripal_get_dbxref: The identifier passed in is expected to be an array with the key
@@ -224,7 +228,7 @@ function tripal_get_dbxref($identifiers, $options = array()) {
     );
   }
 
-  // If one of the identifiers is property then use chado_get_record_with_property()
+  // If one of the identifiers is property then use chado_get_record_with_property().
   if (isset($identifiers['property'])) {
     $property = $identifiers['property'];
     unset($identifiers['property']);
@@ -235,12 +239,13 @@ function tripal_get_dbxref($identifiers, $options = array()) {
     );
   }
 
-  // Else we have a simple case and we can just use chado_generate_var to get the analysis
+  // Else we have a simple case and we can just use chado_generate_var to get 
+  // the analysis.
   else {
     $dbxref = chado_generate_var('dbxref', $identifiers, $options);
   }
 
-  // Ensure the dbxref is singular. If it's an array then it is not singular
+  // Ensure the dbxref is singular. If it's an array then it is not singular.
   if (is_array($dbxref)) {
     tripal_report_error('tripal_db_api', TRIPAL_ERROR,
       "tripal_get_dbxref: The identifiers you passed in were not unique. You passed in %identifier.",
@@ -248,7 +253,8 @@ function tripal_get_dbxref($identifiers, $options = array()) {
     );
   }
 
-  // Report an error if $dbxref is FALSE since then chado_generate_var has failed
+  // Report an error if $dbxref is FALSE since then chado_generate_var has 
+  // failed.
   elseif ($dbxref === FALSE) {
     tripal_report_error(
       'tripal_db_api',
@@ -283,6 +289,8 @@ function tripal_get_dbxref($identifiers, $options = array()) {
  *
  * @return
  *   A string containing the URL.
+ * 
+ * @ingroup tripal_chado_database_api
  */
 function tripal_get_dbxref_url($dbxref) {
   $final_url = '';
@@ -316,13 +324,14 @@ function tripal_get_dbxref_url($dbxref) {
  * Adds a new database to the Chado DB table and returns the DB object.
  *
  * @param $values
- *   An associative array of the values of the db (those to be inserted)
- *   - name: The name of the database. This name is usually used as the prefix for
- *     CV term accessions
- *   - description: (Optional) A description of the database.  By default no description is required.
- *   - url: (Optional) The URL for the database
- *   - urlprefix: (Optional) The URL that is to be used as a prefix when constructing a
- *     link to a database term
+ *   An associative array of the values of the db (those to be inserted):
+ *   - name: The name of the database. This name is usually used as the prefix 
+ *     for CV term accessions.
+ *   - description: (Optional) A description of the database.  By default no 
+ *     description is required.
+ *   - url: (Optional) The URL for the database.
+ *   - urlprefix: (Optional) The URL that is to be used as a prefix when 
+ *     constructing a link to a database term.
  * @param $options
  *   Optional. An associative array of options that can include:
  *   - update_existing: Set this to '1' to force an update of the database if it
@@ -337,14 +346,14 @@ function tripal_get_dbxref_url($dbxref) {
  */
 function tripal_insert_db($values, $options = array()) {
 
-  // Default Values
+  // Default Values.
   $dbname = $values['name'];
   $description = (isset($values['description'])) ? $values['description'] : '';
   $url = (isset($values['url'])) ? $values['url'] : '';
   $urlprefix = (isset($values['urlprefix'])) ? $values['urlprefix'] : '';
   $update = (isset($options['update_existing'])) ? $options['update_existing'] : TRUE;
 
-  // build the values array for inserting/updating
+  // Build the values array for inserting/updating.
   $ins_values = array(
     'name' => $dbname,
     'description' => $description,
@@ -352,11 +361,11 @@ function tripal_insert_db($values, $options = array()) {
     'urlprefix' => $urlprefix
   );
 
-  // get the database record if it already exists
+  // Get the database record if it already exists.
   $sel_values = array('name' => $dbname);
   $result = chado_select_record('db', array('*'), $sel_values);
 
-  // if it does not exists then add it
+  // If it does not exists then add it.
   if (count($result) == 0) {
     $ins_options = array('statement_name' => 'ins_db_nadeurur');
     $success = chado_insert_record('db', $ins_values, $ins_options);
@@ -366,7 +375,7 @@ function tripal_insert_db($values, $options = array()) {
     }
     $result = chado_select_record('db', array('*'), $sel_values);
   }
-  // if it exists and update is enabled the do the update
+  // If it exists and update is enabled the do the update.
   elseif ($update) {
     $upd_options = array('statement_name' => 'upd_db_nadeurur');
     $success = chado_update_record('db', $sel_values, $ins_values, $upd_options);
@@ -377,20 +386,20 @@ function tripal_insert_db($values, $options = array()) {
     $result = chado_select_record('db', array('*'), $sel_values);
   }
 
-  // return the database object
+  // Return the database object.
   return $result[0];
 
 }
 
 /**
- * Add a database reference
+ * Add a database reference.
  *
  * @param $values
  *   An associative array of the values to be inserted including:
- *    - db_id: the database_id of the database the reference is from
- *    - accession: the accession
- *    - version: (Optional) The version of the database reference
- *    - description: (Optional) A description of the database reference
+ *    - db_id: the database_id of the database the reference is from.
+ *    - accession: the accession.
+ *    - version: (Optional) The version of the database reference.
+ *    - description: (Optional) A description of the database reference.
  *
  * @return
  *   The newly inserted dbxref as an object, similar to that returned by
@@ -412,7 +421,7 @@ function tripal_insert_dbxref($values) {
     'description' => $description
   );
 
-  // check to see if the dbxref exists
+  // Check to see if the dbxref exists.
   $sel_values = array(
     'db_id'     => $db_id,
     'accession' => $accession,
@@ -420,7 +429,7 @@ function tripal_insert_dbxref($values) {
   );
   $result = chado_select_record('dbxref', array('*'), $sel_values);
 
-  // if it doesn't already exist then add it
+  // If it doesn't already exist then add it.
   if (!$result) {
     $success = chado_insert_record('dbxref', $ins_values);
     if (!$success) {
@@ -439,20 +448,24 @@ function tripal_insert_dbxref($values) {
 }
 
 /**
- * Add a record to a database reference linking table (ie: feature_dbxref)
+ * Add a record to a database reference linking table (ie: feature_dbxref).
  *
  * @param $basetable
- *   The base table for which the dbxref should be associated. Thus to associate a dbxref
- *   with a feature the basetable=feature and dbxref_id is added to the feature_dbxref table
+ *   The base table for which the dbxref should be associated. Thus to associate 
+ *   a dbxref with a feature the basetable=feature and dbxref_id is added to the
+ *   feature_dbxref table.
  * @param $record_id
- *   The primary key of the basetable to associate the dbxref with. This should be in integer.
+ *   The primary key of the basetable to associate the dbxref with. This should 
+ *   be in integer.
  * @param $dbxref
- *   An associative array describing the dbxref. Valid keys include: 'accession' => the
- *   accession for the dbxref, 'db_name' => the name of the database the dbxref belongs to;
+ *   An associative array describing the dbxref. Valid keys include: 
+ *   'accession' => the accession for the dbxref, 'db_name' => the name of the 
+ *    database the dbxref belongs to.
  *   'db_id' => the primary key of the database the dbxref belongs to.
  * @param $options
  *   An associative array of options. Valid keys include:
- *    - insert_dbxref: Insert the dbxref if it doesn't already exist. TRUE is the default
+ *    - insert_dbxref: Insert the dbxref if it doesn't already exist. TRUE is 
+ *      the default.
  *
  * @ingroup tripal_chado_database_api
  */
@@ -460,11 +473,11 @@ function tripal_associate_dbxref($basetable, $record_id, $dbxref, $options = arr
   $linking_table = $basetable . '_dbxref';
   $foreignkey_name = $basetable . '_id';
 
-  // Default Values
+  // Default Values.
   $options['insert_dbxref'] = (isset($options['insert_dbxref'])) ? $options['insert_dbxref'] : TRUE;
 
-  // If the dbxref_id is set then we know it already exists
-  // Otherwise, select to check
+  // If the dbxref_id is set then we know it already exists.
+  // Otherwise, select to check.
   if (!isset($dbxref['dbxref_id'])) {
     $values = array(
       'accession' => $dbxref['accession'],
@@ -492,7 +505,7 @@ function tripal_associate_dbxref($basetable, $record_id, $dbxref, $options = arr
       $dbxref['dbxref_id'] = $select[0]->dbxref_id;
     }
     elseif ($options['insert_dbxref']) {
-      // Insert the dbxref
+      // Insert the dbxref.
       $insert = tripal_insert_dbxref($values);
       if (isset($insert->dbxref_id)) {
         $dbxref['dbxref_id'] = $insert->dbxref_id;
@@ -518,7 +531,7 @@ function tripal_associate_dbxref($basetable, $record_id, $dbxref, $options = arr
     }
   }
 
-  // Now add the link between the record & dbxref
+  // Now add the link between the record & dbxref.
   if ($dbxref['dbxref_id'] > 0) {
     $values = array(
       'dbxref_id' => $dbxref['dbxref_id'],
@@ -527,7 +540,7 @@ function tripal_associate_dbxref($basetable, $record_id, $dbxref, $options = arr
 
     $result = chado_select_record($linking_table, array('*'), $values);
 
-    // if it doesn't already exist then add it
+    // If it doesn't already exist then add it.
     if (!$result) {
       $success = chado_insert_record($linking_table, $values);
       if (!$success) {
@@ -555,17 +568,17 @@ function tripal_associate_dbxref($basetable, $record_id, $dbxref, $options = arr
 
 /**
  * This function is intended to be used in autocomplete forms
- * for searching for accession that begin with the provided string
+ * for searching for accession that begin with the provided string.
  *
  * @param $db_id
- *   The DB ID in which to search for the term
+ *   The DB ID in which to search for the term.
  * @param $string
- *   The string to search for
+ *   The string to search for.
  *
  * @return
- *   A json array of terms that begin with the provided string
+ *   A json array of terms that begin with the provided string.
  *
- * @ingroup tripal_db_api
+ * @ingroup tripal_chado_database_api
  */
 function tripal_autocomplete_dbxref($db_id, $string = '') {
   if (!$db_id) {

tripal_chado/api/modules/tripal_chado.feature.api.inc

@@ -16,10 +16,10 @@
  * @param $field
  *   The field in the publication to search on.
  * @param $string
- *   The string to search for
+ *   The string to search for.
  *
  * @return
- *   A json array of terms that begin with the provided string
+ *   A json array of terms that begin with the provided string.
  *
  * @ingroup tripal_feature_api
  */
@@ -47,13 +47,13 @@ function tripal_autocomplete_feature($string = '') {
 }
 
 /**
- * Performs a reverse compliment of a nucleotide sequence
+ * Performs a reverse compliment of a nucleotide sequence.
  *
  * @param $sequence
- *   The nucelotide sequence
+ *   The nucelotide sequence.
  *
  * @return
- *   an upper-case reverse complemented sequence
+ *   an upper-case reverse complemented sequence.
  *
  * @ingroup tripal_feature_api
  */
@@ -87,12 +87,13 @@ function tripal_reverse_compliment_sequence($sequence) {
  * @param $feature
  *   An associative array describing the feature. Valid keys include:
  *    - feature_id: The feature_id of the feature for which the sequence will
- *      be retrieved
- *    - name: The feature name. This will appear on the FASTA definition line
+ *      be retrieved.
+ *    - name: The feature name. This will appear on the FASTA definition line.
  *    - parent_id:  (optional) only retrieve a sequence if 'derive_from_parent'
  *      is true and the parent matches this ID.
- *    - featureloc_id: (optional) only retrieve a sequence if 'derive_from_parent' is
- *      true and the alignment is defined with this featureloc_id
+ *    - featureloc_id: (optional) only retrieve a sequence if 
+ *      'derive_from_parent' is true and the alignment is defined with this 
+ *      featureloc_id.
  * @param $options
  *   An associative array of options. Valid keys include:
  *    - width: Indicate the number of bases to use per line.  A new line will
@@ -105,28 +106,28 @@ function tripal_reverse_compliment_sequence($sequence) {
  *      excluding intro sub feature sequence.  For example, set this option to
  *      obtain just the coding sequence of an mRNA.
  *    - upstream: An integer specifing the number of upstream bases to include
- *      in the output
+ *      in the output.
  *    - downstream: An integer specifying the number of downstream bases to
  *      include in the output.
  *    - sub_feature_types: Only include sub features (or child features) of
- *      the types provided in the array
+ *      the types provided in the array.
  *    - relationship_type: If a relationship name is provided (e.g. sequence_of)
  *      then any sequences that are in relationships of this type with matched
- *      sequences are also included
+ *      sequences are also included.
  *    - relationship_part: If a relationship is provided in the preceeding
  *      argument then the rel_part must be either 'object' or 'subject' to
- *      indicate which side of the relationship the matched features belong
+ *      indicate which side of the relationship the matched features belong.
  *
  * @return
  *   an array of matching sequence in the following keys for each sequence:
- *      'types'         => an array of feature types that were used to derive
- *         the sequence (e.g. from an aggregated sequence)
- *      'upstream'      => the number of upstream bases included in the sequence
- *      'downstream'    => the number of downstream bases included in the
- *        sequence
- *      'defline'       => the definintion line used to create a FASTA sequence
- *      'residues'      => the residues
- *      'featureloc_id' => the featureloc_id if the sequences is from an
+ *    - types: an array of feature types that were used to derive
+ *      the sequence (e.g. from an aggregated sequence)
+ *    - upstream: the number of upstream bases included in the sequence
+ *    - downstream: the number of downstream bases included in the
+ *      sequence
+ *    - defline: the definintion line used to create a FASTA sequence
+ *    - residues: the residues
+ *    - featureloc_id: the featureloc_id if the sequences is from an
  *        alignment
  *
  * @ingroup tripal_feature_api
@@ -341,7 +342,7 @@ function tripal_get_feature_sequences($feature, $options) {
       if ($parent_id and $parent_id != $parent->srcfeature_id) {
         continue;
       }
-      // if the user specified a particular featureloc_id and this one
+      // If the user specified a particular featureloc_id and this one
       // doesn't match then skip it.
       if ($featureloc_id and $featureloc_id != $parent->featureloc_id) {
         continue;
@@ -351,8 +352,8 @@ function tripal_get_feature_sequences($feature, $options) {
       $notes = '';
       $types = array();
 
-      // if we are to aggregate then we will ignore the feature returned
-      // by the query above and rebuild it using the sub features
+      // If we are to aggregate then we will ignore the feature returned
+      // by the query above and rebuild it using the sub features.
       if ($aggregate) {
 
         // now get the sub features that are located on the parent.
@@ -382,13 +383,14 @@ function tripal_get_feature_sequences($feature, $options) {
             continue;
           }
 
-          // keep up with the types
+          // Keep up with the types.
           if (!in_array($child->type_name, $types)) {
             $types[] = $child->type_name;
           }
 
-          // if the first sub feature we need to include the upstream bases. first check if
-          // the feature is in the foward direction or the reverse.
+          // If the first sub feature we need to include the upstream bases. 
+          // First check if the feature is in the foward direction or the 
+          // reverse.
           if ($i == 0 and $parent->strand >= 0) {  // forward direction
             // -------------------------- ref
             //    ....---->  ---->
@@ -402,8 +404,9 @@ function tripal_get_feature_sequences($feature, $options) {
             $q = chado_query($parent_sql, array(':upstream' => 0, ':downstream' => $downstream, ':feature_id' => $child->feature_id));
           }
 
-          // Next, if the last sub feature we need to include the downstream bases. first check if
-          // the feature is in teh forward direction or the reverse
+          // Next, if the last sub feature we need to include the downstream 
+          // bases. First check if the feature is in teh forward direction or 
+          // the reverse.
           elseif ($i == $num_children - 1 and $parent->strand >= 0) {  // forward direction
             // -------------------------- ref
             //        ---->  ---->....
@@ -416,7 +419,7 @@ function tripal_get_feature_sequences($feature, $options) {
             //          1       2  up
             $q = chado_query($parent_sql, array(':upstream' => $upstream, ':downstream' => 0, ':feature_id' => $child->feature_id));
           }
-          // for internal sub features we don't want upstream or downstream bases
+          // For internal sub features we don't want upstream or downstream bases.
           else {
             $q = chado_query($parent_sql, array(':upstream' => 0, ':downstream' => 0, ':feature_id' => $child->feature_id));
           }
@@ -435,7 +438,7 @@ function tripal_get_feature_sequences($feature, $options) {
           $i++;
         }
       }
-      // if this isn't an aggregate then use the parent residues
+      // If this isn't an aggregate then use the parent residues.
       else {
          $seq = $parent->residues;
          if ($parent->upstream > 0) {
@@ -446,14 +449,14 @@ function tripal_get_feature_sequences($feature, $options) {
          }
       }
 
-      // get the reverse compliment if feature is on the reverse strand
+      // Get the reverse compliment if feature is on the reverse strand.
       $dir = 'forward';
       $length = strlen($seq);
       if ($parent->strand < 0) {
         $seq = tripal_reverse_compliment_sequence($seq);
         $dir = 'reverse';
       }
-      // now format for display
+      // Now format for display.
       if ($is_html) {
         $seq = wordwrap($seq, $num_bases_per_line, "<br>", TRUE);
       }
@@ -513,10 +516,10 @@ function tripal_get_feature_sequences($feature, $options) {
       $residues = wordwrap($residues, $num_bases_per_line, "\r\n", TRUE);
     }
 
-    // get the definintion line for this feature
+    // Get the definintion line for this feature.
     $defline = tripal_get_fasta_defline($f, '', NULL, '', $length);
 
-    // add to the sequence array
+    // Add to the sequence array.
     $sequences[] = array(
       'types'      => $f->type_id->name,
       'upstream'   => 0,
@@ -531,6 +534,7 @@ function tripal_get_feature_sequences($feature, $options) {
 }
 
 /**
+ * Retrieves the bulk sequences for a given feature.
  *
  * @param $options
  *   An associative array of options for selecting a feature. Valid keys include:
@@ -582,7 +586,7 @@ function tripal_get_feature_sequences($feature, $options) {
  */
 function tripal_get_bulk_feature_sequences($options) {
 
-  // default values for building the sequence
+  // Default values for building the sequence
   $org_commonname     = array_key_exists('org_commonname', $options)     ? $options['org_commonname']    : '';
   $genus              = array_key_exists('genus', $options)              ? $options['genus']             : '';
   $species            = array_key_exists('species', $options)            ? $options['species']           : '';
@@ -604,7 +608,7 @@ function tripal_get_bulk_feature_sequences($options) {
     return;
   }
 
-  // get the list of features
+  // Get the list of features.
   $vars = array();
   $sql  = "
     SELECT DISTINCT F.feature_id, F.name, F.uniquename,
@@ -643,7 +647,7 @@ function tripal_get_bulk_feature_sequences($options) {
         $sql .= ":fname$i, ";
         $vars[":fname$i"] = $fname;
       }
-      // remove the trailing comma and close the paren
+      // Remove the trailing comma and close the parenthesis.
       $sql = substr($sql, 0, -2) . ")";
     }
     else {
@@ -658,7 +662,7 @@ function tripal_get_bulk_feature_sequences($options) {
         $sql .= ":funame$i, ";
         $vars[":funame$i"] = $funame;
       }
-      // remove the trailing comma and close the paren
+      // Remove the trailing comma and close the parenthesis.
       $sql = substr($sql, 0, -2) . ")";
     }
     else {
@@ -686,30 +690,34 @@ function tripal_get_bulk_feature_sequences($options) {
 }
 
 /**
- * Returns a definition line that can be used in a FASTA file
+ * Returns a definition line that can be used in a FASTA file.
  *
  * @param $feature
- *   A single feature object containing all the fields from the chado.feature table.
- *   Best case is to provide an object generated by the chado_generate_var() function.
+ *   A single feature object containing all the fields from the chado.feature 
+ *   table. Best case is to provide an object generated by the 
+ *   chado_generate_var() function.
  * @param $notes
- *   Optional: additional notes to be added to the definition line
+ *   Optional: additional notes to be added to the definition line.
  * @param $featureloc
- *   Optional: a single featureloc object generated using chado_generate_var that
- *   contains a record from the chado.featureloc table. Provide this if the
- *   sequence was obtained by using the alignment rather than from the feature.residues
- *   column
+ *   Optional: a single featureloc object generated using chado_generate_var
+ *   that contains a record from the chado.featureloc table. Provide this if the
+ *   sequence was obtained by using the alignment rather than from the 
+ *   feature.residues column.
  * @param $type
  *   Optional: the type of sequence. By default the feature type is used.
  * @param $length
- *   Optional: the length of the sequence
+ *   Optional: the length of the sequence.
  *
  * @return
  *   A string of the format: uniquename|name|type|feature_id
- *   or if an alignment:  srcfeature_name:fmin..fmax[+-]; alignment of uniquename|name|type|feature_id
+ *   or if an alignment:  srcfeature_name:fmin..fmax[+-]; alignment of 
+ *   uniquename|name|type|feature_id.
+ * 
+ * @ingroup tripal_feature_api
  */
 function tripal_get_fasta_defline($feature, $notes = '', $featureloc = NULL, $type = '', $length = 0) {
 
-  // make sure the featureloc object has the srcfeature if not, then add it
+  // Make sure the featureloc object has the srcfeature if not, then add it.
   if ($featureloc) {
     if (!is_object($featureloc->srcfeature_id)) {
       $featureloc->srcfeature_id = chado_generate_var('feature', array('feature_id' => $featureloc->srcfeature_id));
@@ -718,17 +726,17 @@ function tripal_get_fasta_defline($feature, $notes = '', $featureloc = NULL, $ty
       $featureloc->srcfeature_id->organism_id = chado_generate_var('organism', array('organism_id' => $featureloc->srcfeature_id->organism_id));
     }
   }
-  // make sure the feature object has the organism if not, then add it
+  // Make sure the feature object has the organism if not, then add it.
   if (!is_object($feature->organism_id)) {
     $feature->organism_id = chado_generate_var('organism', array('organism_id' => $feature->organism_id));
   }
 
-  // if a type is not provided then use the default type
+  // If a type is not provided then use the default type.
   if (!$type) {
     $type = $feature->type_id->name;
   }
 
-  // construct the definition line
+  // Construct the definition line.
   $defline = $feature->uniquename . " " .
              'ID=' . $feature->uniquename . "|" .
              'Name=' . $feature->name . "|" .
@@ -749,11 +757,16 @@ function tripal_get_fasta_defline($feature, $notes = '', $featureloc = NULL, $ty
 }
 
 /**
- * Returns a string representing a feature location in an alignment
+ * Returns a string representing a feature location in an alignment.
  *
- * @param unknown $featureloc
+ * @param $featureloc
  *   A single featureloc object generated using chado_generate_var that
  *   contains a record from the chado.featureloc table.
+ *
+ *  @return
+ *   A string of the format: uniquename:featurelocmin..featurelocmax.strand
+ * 
+ * @ingroup tripal_feature_api
  */
 function tripal_get_location_string($featureloc) {
   $feature = $featureloc->feature_id;
@@ -774,10 +787,10 @@ function tripal_get_location_string($featureloc) {
  * Quickly retrieves relationships for a feature.
  *
  * Using the chado_expand_var function to retrieve a set
- * of relationships can be very slow, especialy if there are many relationships
+ * of relationships can be very slow, especialy if there are many relationships.
  * This function is intended to help speed up the retrieval of relationships
  * by only retrieving the base information for the relationship and returning
- * an array with
+ * an array.
  *
  * @param $feature
  *   The feature object
@@ -788,13 +801,13 @@ function tripal_get_location_string($featureloc) {
  * @ingroup tripal_feature_api
  */
 function tripal_get_feature_relationships($feature) {
-  // expand the feature object to include the feature relationships.
+  // Expand the feature object to include the feature relationships.
   $options = array(
     'return_array' => 1,
     'order_by' => array('rank' => 'ASC'),
-    // we don't want to fully recurse we only need information about the
-    // relationship type and the object and subject features (including feature type
-    // and organism)
+    // We don't want to fully recurse we only need information about the
+    // relationship type and the object and subject features (including feature 
+    // type and organism).
     'include_fk' => array(
       'type_id' => 1,
       'object_id' => array(
@@ -809,13 +822,13 @@ function tripal_get_feature_relationships($feature) {
   );
   $feature = chado_expand_var($feature, 'table', 'feature_relationship', $options);
 
-  // get the subject relationships
+  // Get the subject relationships.
   $srelationships = $feature->feature_relationship->subject_id;
   $orelationships = $feature->feature_relationship->object_id;
 
 
-  // get alignment as child. The $feature->featureloc element
-  // is already populated from the alignment preprocess function
+  // Get alignment as child. The $feature->featureloc element
+  // is already populated from the alignment preprocess function.
   $options = array(
     'return_array' => 1,
     'include_fk' => array(
@@ -832,7 +845,7 @@ function tripal_get_feature_relationships($feature) {
     $cfeaturelocs = array($cfeaturelocs);
   }
 
-  // prepare the SQL statement to get the featureloc for the
+  // Prepare the SQL statement to get the featureloc for the
   // feature in the relationships.
   $flrels_sql = "
     SELECT
@@ -843,22 +856,23 @@ function tripal_get_feature_relationships($feature) {
     WHERE FL.feature_id = :feature_id and FL.srcfeature_id = :srcfeature_id
   ";
 
-  // combine both object and subject relationshisp into a single array
+  // Combine both object and subject relationshisp into a single array.
   $relationships = array();
   $relationships['object'] = array();
   $relationships['subject'] = array();
 
-  // iterate through the object relationships
+  // Iterate through the object relationships.
   if ($orelationships) {
     foreach ($orelationships as $relationship) {
       $rel = new stdClass();
-      // get locations where the child feature and this feature overlap with the
+      // Get locations where the child feature and this feature overlap with the
       // same landmark feature.
       $rel->child_featurelocs = array();
       foreach ($cfeaturelocs as $featureloc) {
         $res = chado_query($flrels_sql, array(':feature_id' => $relationship->subject_id->feature_id, ':srcfeature_id' => $featureloc->srcfeature_id->feature_id));
         while ($loc = $res->fetchObject()) {
-          // add in the node id of the src feature if it exists and save this location
+          // Add in the node id of the src feature if it exists and save this 
+          // location.
           if (property_exists($featureloc->srcfeature_id, 'nid')) {
             $loc->nid = $featureloc->srcfeature_id->nid;
           }
@@ -867,7 +881,7 @@ function tripal_get_feature_relationships($feature) {
       }
       $rel->record = $relationship;
 
-      // get the relationship and child types
+      // Get the relationship and child types.
       $rel_type = t(preg_replace('/_/', " ", $relationship->type_id->name));
       $child_type = $relationship->subject_id->type_id->name;
 
@@ -888,16 +902,17 @@ function tripal_get_feature_relationships($feature) {
     }
   }
 
-  // now add in the subject relationships
+  // Now add in the subject relationships.
   if ($srelationships) {
     foreach ($srelationships as $relationship) {
       $rel = new stdClass();
-      // get locations where this feature overlaps with the parent
+      // Get locations where this feature overlaps with the parent.
       $rel->parent_featurelocs = array();
       foreach ($cfeaturelocs as $featureloc) {
         $res = chado_query($flrels_sql, array(':feature_id' => $relationship->object_id->feature_id, ':srcfeature_id' => $featureloc->srcfeature_id->feature_id));
         while ($loc = $res->fetchObject()) {
-          // add in the node id of the src feature if it exists and save this location
+          // Add in the node id of the src feature if it exists and save this 
+          // location.
           if (property_exists($featureloc->srcfeature_id, 'nid')) {
             $loc->nid = $featureloc->srcfeature_id->nid;
           }
@@ -941,23 +956,24 @@ function chado_get_featureloc_sequences($feature_id, $featurelocs) {
   }
 
   // Get the list of relationships (including any aggregators) and iterate
-  // through each one to find information needed to color-code the reference sequence
+  // through each one to find information needed to color-code the reference 
+  // sequence.
   $relationships = _tripal_feature_get_aggregate_relationships($feature_id);
   if (!$relationships) {
     return array();
   }
 
 
-  // iterate through each of the realtionships features and get their
-  // locations
+  // Iterate through each of the realtionships features and get their
+  // locations.
   foreach ($relationships as $rindex => $rel) {
-    // get the featurelocs for each of the relationship features
+    // Get the featurelocs for each of the relationship features.
     $rel_featurelocs = chado_get_featurelocs($rel->subject_id, 'as_child', 0);
     foreach ($rel_featurelocs as $rfindex => $rel_featureloc) {
-      // keep track of this unique source feature
+      // Keep track of this unique source feature.
       $src = $rel_featureloc->src_feature_id . "-" . $rel_featureloc->src_cvterm_id;
 
-      // copy over the results to the relationship object.  Since there can
+      // Copy over the results to the relationship object.  Since there can
       // be more than one feature location for each relationship feature we
       // use the '$src' variable to keep track of these.
       $rel->featurelocs = new stdClass();
@@ -979,7 +995,7 @@ function chado_get_featureloc_sequences($feature_id, $featurelocs) {
     }
   }
 
-  // the featurelocs array provided to the function contains the locations
+  // The featurelocs array provided to the function contains the locations
   // where this feature is found.   We want to get the sequence for each
   // location and then annotate it with the parts found from the relationships
   // locations determiend above.
@@ -1159,16 +1175,16 @@ function chado_get_feature_relationships($feature_id, $side = 'as_subject') {
 }
 
 /**
- * Load the locations for a given feature
+ * Load the locations for a given feature.
  *
  * @param $feature_id
- *   The feature to look up locations for
+ *   The feature to look up locations for.
  * @param $side
- *   Whether the feature is the scrfeature, 'as_parent', or feature, 'as_child'
+ *   Whether the feature is the scrfeature, 'as_parent', or feature, 'as_child'.
  * @param $aggregate
- *   Whether or not to get the locations for related features
+ *   Whether or not to get the locations for related features.
  *
- * @ingroup tripal_feature
+ * @ingroup tripal_feature_api
  */
 function chado_get_featurelocs($feature_id, $side = 'as_parent', $aggregate = 1) {
 
@@ -1194,12 +1210,12 @@ function chado_get_featurelocs($feature_id, $side = 'as_parent', $aggregate = 1)
 
   $flresults = chado_query($sql, array(':feature_id' => $feature_id));
 
-  // copy the results into an array
+  // Copy the results into an array.
   $i=0;
   $featurelocs = array();
   while ($loc = $flresults->fetchObject()) {
-    // if a drupal entity exists for this feature then add the nid to the
-    // results object
+    // If a drupal entity exists for this feature then add the nid to the
+    // results object.
 
 
     // Get the bundle for this feature type, if one exists.
@@ -1222,17 +1238,17 @@ function chado_get_featurelocs($feature_id, $side = 'as_parent', $aggregate = 1)
       $sbundle = tripal_load_bundle_entity(array('term_id' => $sterm->id));
       $loc->seid = chado_get_record_entity_by_bundle($sbundle, $loc->src_feature_id);
     }
-    // add the result to the array
+    // Add the result to the array.
     $featurelocs[$i++] = $loc;
   }
 
-  // Add the relationship feature locs if aggregate is turned on
+  // Add the relationship feature locs if aggregate is turned on.
   if ($aggregate and strcmp($side, 'as_parent')==0) {
-  // get the relationships for this feature without substituting any children
-  // for the parent. We want all relationships
+  // Get the relationships for this feature without substituting any children
+  // for the parent. We want all relationships.
   $relationships = _tripal_feature_get_aggregate_relationships($feature_id, 0);
   foreach ($relationships as $rindex => $rel) {
-    // get the featurelocs for each of the relationship features
+    // Get the featurelocs for each of the relationship features.
     $rel_featurelocs = tripal_feature_load_featurelocs($rel->subject_id, 'as_child', 0);
       foreach ($rel_featurelocs as $findex => $rfloc) {
         $featurelocs[$i++] = $rfloc;
@@ -1245,13 +1261,15 @@ function chado_get_featurelocs($feature_id, $side = 'as_parent', $aggregate = 1)
 }
 
 /**
- * Get features related to the current feature to a given depth. Recursive function.
+ * Get features related to the current feature to a given depth. 
+ * Recursive function.
  *
  * @param $feature_id
  * @param $substitute
  * @param $levels
  * @param $base_type_id
  * @param $depth
+ * 
  *
  */
 function _tripal_feature_get_aggregate_relationships($feature_id, $substitute=1,
@@ -1275,7 +1293,9 @@ function _tripal_feature_get_aggregate_relationships($feature_id, $substitute=1,
  * @param $feature_id
  *   The feature to get relationships for
  * @param $side
- *   The side of the relationship this feature is (ie: 'as_subject' or 'as_object')
+ *   The side of the relationship this feature is (ie: 'as_subject' or 
+ *   'as_object')
+ * 
  *
  */
 function _tripal_feature_load_relationships($feature_id, $side = 'as_subject') {
@@ -1326,10 +1346,13 @@ function _tripal_feature_load_relationships($feature_id, $side = 'as_subject') {
   return $relationships;
 }
 /**
-  * Used to sort the list of relationship parts by start position
-  *
-  * @ingroup tripal_feature
-  */
+ * Used to sort the list of relationship parts by start position.
+ * 
+ * @param $a
+ * @param $b
+ * 
+ * @ingroup tripal_feature_api
+ */
 function chado_feature__residues_sort_rel_parts_by_start($a, $b) {
   foreach ($a as $type_name => $details) {
     $astart = $a[$type_name]['start'];
@@ -1342,17 +1365,17 @@ function chado_feature__residues_sort_rel_parts_by_start($a, $b) {
   return strnatcmp($astart, $bstart);
 }
 /**
- * Used to sort the feature locs by start position
+ * Used to sort the feature locs by start position.
  *
  * @param $a
- *   One featureloc record (as an object)
+ *   One featureloc record (as an object).
  * @param $b
- *   The other featureloc record (as an object)
+ *   The other featureloc record (as an object).
  *
  * @return
- *   Which feature location comes first
+ *   Which feature location comes first.
  *
- * @ingroup tripal_feature
+ * @ingroup tripal_feature_api
  */
 function chado_feature__residues_sort_locations($a, $b) {
   return strnatcmp($a->fmin, $b->fmin);

tripal_chado/api/modules/tripal_chado.organism.api.inc

@@ -12,41 +12,43 @@
  */
 
 /**
- * Retrieves a chado organism variable
+ * Retrieves a chado organism variable.
  *
  * @param $identifier
- *   An array with the key stating what the identifier is. Supported keys (only on of the
- *   following unique keys is required):
- *    - organism_id: the chado organism.organism_id primary key
- *    - genus & species: the chado organism.genus field & organism.species field
+ *   An array with the key stating what the identifier is. Supported keys (only 
+ *   on of the following unique keys is required):
+ *    - organism_id: the chado organism.organism_id primary key.
+ *    - genus & species: the chado organism.genus field & organism.species field.
  *   There are also some specially handled keys. They are:
- *    - property: An array/object describing the property to select records for. It
- *      should at least have either a type_name (if unique across cvs) or type_id. Other
- *      supported keys include: cv_id/cv_name (of the type), value and rank
+ *    - property: An array/object describing the property to select records for. 
+ *      It should at least have either a type_name (if unique across cvs) or 
+ *      type_id. Other supported keys include: cv_id/cv_name (of the type), 
+ *      value and rank.
  * @param $options
  *   An array of options. Supported keys include:
- *     - Any keys supported by chado_generate_var(). See that function definition for
- *       additional details.
+ *     - Any keys supported by chado_generate_var(). See that function 
+ *      definition for additional details.
  *
- * NOTE: the $identifier parameter can really be any array similar to $values passed into
- *   chado_select_record(). It should fully specify the organism record to be returned.
+ * NOTE: the $identifier parameter can really be any array similar to $values 
+ * passed into chado_select_record(). It should fully specify the organism 
+ * record to be returned.
  *
  * @return
- *   If unique values were passed in as an identifier then an object describing the organism
- *   will be returned (will be a chado variable from chado_generate_var()). Otherwise,
- *   FALSE will be returned.
+ *   If unique values were passed in as an identifier then an object describing 
+ *   the organism will be returned (will be a chado variable from 
+ *   chado_generate_var()). Otherwise, FALSE will be returned.
  *
  * @ingroup tripal_organism_api
  */
 function tripal_get_organism($identifiers, $options = array()) {
 
-  // Set Defaults
+  // Set Defaults.
   if (!isset($options['include_fk'])) {
-    // Tells chado_generate_var not to follow any foreign keys
+    // Tells chado_generate_var not to follow any foreign keys.
     $options['include_fk'] = array();
   }
 
-  // Error Checking of parameters
+  // Error Checking of parameters.
   if (!is_array($identifiers)) {
     tripal_report_error(
       'tripal_organism_api',
@@ -71,7 +73,7 @@ function tripal_get_organism($identifiers, $options = array()) {
     );
   }
 
-  // If one of the identifiers is property then use chado_get_record_with_property()
+  // If one of the identifiers is property then use chado_get_record_with_property().
   if (isset($identifiers['property'])) {
     $property = $identifiers['property'];
     unset($identifiers['property']);
@@ -82,7 +84,8 @@ function tripal_get_organism($identifiers, $options = array()) {
     );
   }
 
-  // Else we have a simple case and we can just use chado_generate_var to get the analysis
+  // Else we have a simple case and we can just use chado_generate_var to get 
+  // the analysis.
   else {
 
     // Try to get the organism
@@ -93,7 +96,7 @@ function tripal_get_organism($identifiers, $options = array()) {
     );
   }
 
-  // Ensure the organism is singular. If it's an array then it is not singular
+  // Ensure the organism is singular. If it's an array then it is not singular.
   if (is_array($organism)) {
     tripal_report_error(
       'tripal_organism_api',
@@ -105,7 +108,8 @@ function tripal_get_organism($identifiers, $options = array()) {
     );
   }
 
-  // Report an error if $organism is FALSE since then chado_generate_var has failed
+  // Report an error if $organism is FALSE since then chado_generate_var has 
+  // failed.
   elseif ($organism === FALSE) {
     tripal_report_error(
       'tripal_organism_api',
@@ -141,7 +145,7 @@ function tripal_get_organism_scientific_name($organism) {
   // For Chado v1.3 we have a type_id and infraspecific name.
   if (property_exists($organism, 'type_id')) {
     $rank = '';
-    // For organism objects crated using chado_generate_var
+    // For organism objects crated using chado_generate_var.
     if (is_object($organism->type_id)) {
       if ($organism->type_id) {
         $rank = $orgasnism->type_id->name;
@@ -166,14 +170,15 @@ function tripal_get_organism_scientific_name($organism) {
 }
 
 /**
- * Returns a list of organisms that are currently synced with Drupal to use in select lists
+ * Returns a list of organisms that are currently synced with Drupal to use in 
+ * select lists.
  *
  * @param $syncd_only
- *   Whether or not to return all chado organisms or just those sync'd with drupal. Defaults
- *   to TRUE (only sync'd organisms)
+ *   Whether or not to return all chado organisms or just those sync'd with 
+ *   drupal. Defaults to TRUE (only sync'd organisms).
  * @return
- *   An array of organisms sync'd with Drupal where each value is the organism scientific
- *   name and the keys are organism_id's
+ *   An array of organisms sync'd with Drupal where each value is the organism 
+ *   scientific name and the keys are organism_id's.
  *
  * @ingroup tripal_organism_api
  */
@@ -190,7 +195,7 @@ function tripal_get_organism_select_options($syncd_only = TRUE) {
     ";
     $orgs = chado_query($sql);
 
-    // iterate through the organisms and build an array of those that are synced
+    // Iterate through the organisms and build an array of those that are synced.
     foreach ($orgs as $org) {
       $org_list[$org->organism_id] = $org->genus . ' ' . $org->species;
     }
@@ -200,7 +205,7 @@ function tripal_get_organism_select_options($syncd_only = TRUE) {
     $csql =  "SELECT * FROM {organism} ORDER BY genus, species";
     $orgs = chado_query($csql);
 
-    // iterate through the organisms and build an array of those that are synced
+    // Iterate through the organisms and build an array of those that are synced.
     foreach ($orgs as $org) {
       $org_list[$org->organism_id] = $org->genus . ' ' . $org->species;
     }
@@ -212,11 +217,11 @@ function tripal_get_organism_select_options($syncd_only = TRUE) {
  * Return the path for the organism image.
  *
  * @param $organism
- *   An organism table record
+ *   An organism table record.
  *
  * @return
  *   If the type parameter is 'url' (the default) then the fully qualified
- *   url to the image is returend. If no image is present then NULL is returned
+ *   url to the image is returend. If no image is present then NULL is returned.
  *
  * @ingroup tripal_organism_api
  */
@@ -227,7 +232,7 @@ function tripal_get_organism_image_url($organism) {
     return NULL;
   }
 
-  // Get the organism's node
+  // Get the organism's node.
   $nid = chado_get_nid_from_id('organism', $organism->organism_id);
 
   // Look in the file_usage table of Drupal for the image file. This
@@ -245,8 +250,8 @@ function tripal_get_organism_image_url($organism) {
     return file_create_url($file->uri);
   }
 
-  // First look for an image with the genus/species name.  This is old-style tripal
-  // and we keep it for backwards compatibility.
+  // First look for an image with the genus/species name.  This is old-style 
+  // tripal and we keep it for backwards compatibility.
   $base_path = realpath('.');
   $image_dir = tripal_get_files_dir('tripal_organism') . "/images";
   $image_name =  $organism->genus . "_" . $organism->species . ".jpg";
@@ -272,13 +277,13 @@ function tripal_get_organism_image_url($organism) {
 
 /**
  * This function is intended to be used in autocomplete forms
- * for searching for organisms that begin with the provided string
+ * for searching for organisms that begin with the provided string.
  *
  * @param $text
- *   The string to search for
+ *   The string to search for.
  *
  * @return
- *   A json array of terms that begin with the provided string
+ *   A json array of terms that begin with the provided string.
  *
  * @ingroup tripal_organism_api
  */

tripal_chado/api/modules/tripal_chado.phylotree.api.inc

@@ -88,14 +88,14 @@ function tripal_validate_phylotree($val_type, &$options, &$errors, &$warnings) {
       $errors['format'] = t('Please provide a file format for the tree file.');
       return FALSE;
     }
-    // Make sure the file format is correct
+    // Make sure the file format is correct.
     if ($options['format'] != 'newick' and $options['format'] != 'taxonomy') {
       $errors['format'] = t('The file format is not supported. Currently only the "newick" file format is supported.');
       return FALSE;
     }
   }
   else {
-    // Does the phylotree ID exist and is it valid
+    // Does the phylotree ID exist and is it valid.
     if (!array_key_exists('phylotree_id', $options)) {
       $errors['phylotree_id'] = t('Please provide the ID for the tree.');
       return FALSE;
@@ -109,7 +109,7 @@ function tripal_validate_phylotree($val_type, &$options, &$errors, &$warnings) {
 
   }
 
-  // Make sure the file exists if one is specified
+  // Make sure the file exists if one is specified.
   if (array_key_exists('tree_file', $options) and $options['tree_file']) {
     // If this is a numeric Drupal file then all is good, no need to check.
     if (!is_numeric($options['tree_file'])) {
@@ -118,7 +118,7 @@ function tripal_validate_phylotree($val_type, &$options, &$errors, &$warnings) {
         return FALSE;
       }
     }
-    // Make sure the file format is correct
+    // Make sure the file format is correct.
     if (!array_key_exists('format', $options) or
         ($options['format'] != 'newick' and $options['format'] != 'taxonomy')) {
       $errors['format'] = t('Please provide a supported file format. Currently only the "newick" file format is supported.');
@@ -204,7 +204,7 @@ function tripal_validate_phylotree($val_type, &$options, &$errors, &$warnings) {
     $options['dbxref_id'] = $dbxref->dbxref_id;
   }
 
-  // Make sure the tree name is unique
+  // Make sure the tree name is unique.
   if (array_key_exists('name', $options) and $options['name']) {
     $sql = "
       SELECT *
@@ -249,6 +249,7 @@ function tripal_validate_phylotree($val_type, &$options, &$errors, &$warnings) {
  *     'tree_file':  The path of the file containing the phylogenetic tree to
  *                   import or a Drupal managed_file numeric ID.
  *     'format':     The file format. Currently only 'newick is supported'.
+ * 
  *  Optional keys:
  *     'dbxref':     A database cross-reference of the form DB:ACCESSION.
  *                   Where DB is the database name, which is already present
@@ -452,7 +453,7 @@ function tripal_update_phylotree($phylotree_id, &$options) {
     );
   }
 
-  // If we have a tree file, then import the tree
+  // If we have a tree file, then import the tree.
   if (array_key_exists('tree_file', $options) and $options['tree_file']) {
 
     // Remove any existing nodes
@@ -530,7 +531,7 @@ function tripal_update_phylotree($phylotree_id, &$options) {
  */
 function tripal_delete_phylotree($phylotree_id) {
 
-  // if we don't have a phylotree id for this node then this isn't a node of
+  // If we don't have a phylotree id for this node then this isn't a node of
   // type chado_phylotree or the entry in the chado_phylotree table was lost.
   if (!$phylotree_id) {
     tripal_report_error('tripal_phylogeny', TRIPAL_ERROR,
@@ -544,7 +545,7 @@ function tripal_delete_phylotree($phylotree_id) {
 }
 
 /**
- * Iterates through the tree and sets the left and right indicies .
+ * Iterates through the tree and sets the left and right indicies.
  *
  * @param $tree
  *   The tree array.
@@ -642,14 +643,14 @@ function tripal_phylogeny_import_tree(&$tree, $phylotree, $options, $vocab = arr
       'left_idx'  => $tree['left_index'],
       'right_idx' => $tree['right_index'],
     );
-    // Add in any optional values to the $values array if they are present
+    // Add in any optional values to the $values array if they are present.
     if (!empty($tree['name']) and $tree['name'] != '') {
       $values['label'] = $tree['name'];
     }
     if (!empty($tree['length']) and $tree['length'] != '') {
       $values['distance'] = $tree['length'];
     }
-    // Set the type of node
+    // Set the type of node.
     if ($tree['is_root']) {
       $values['type_id'] = $vocab['root']->cvterm_id;
     }
@@ -669,8 +670,9 @@ function tripal_phylogeny_import_tree(&$tree, $phylotree, $options, $vocab = arr
       if (!empty($tree['name']) and $tree['name'] != '') {
         if (!$options['taxonomy']) {
 
-          // This is a sequence-based tree. Try to match leaf nodes with features.
-          // First, Get the Name and uniquename for the feature
+          // This is a sequence-based tree. Try to match leaf nodes with 
+          // features.
+          // First, Get the Name and uniquename for the feature.
           $matches = array();
           $sel_values = array();
           if ($options['match'] == "name") {
@@ -708,7 +710,7 @@ function tripal_phylogeny_import_tree(&$tree, $phylotree, $options, $vocab = arr
       }
     }
 
-    // Insert the new node and then add it's assigned phylonode_id to the node
+    // Insert the new node and then add it's assigned phylonode_id to the node.
     $phylonode = chado_insert_record('phylonode', $values);
     $tree['phylonode_id'] = $phylonode['phylonode_id'];
 
@@ -722,7 +724,7 @@ function tripal_phylogeny_import_tree(&$tree, $phylotree, $options, $vocab = arr
       $pylonode_organism = chado_insert_record('phylonode_organism', $values);
     }
 
-    // Associate any properties
+    // Associate any properties.
     if (array_key_exists('properties', $tree)) {
       foreach ($tree['properties'] as $type_id => $value) {
         $values = array(
@@ -742,13 +744,15 @@ function tripal_phylogeny_import_tree(&$tree, $phylotree, $options, $vocab = arr
 }
 
 /**
+ * Get the vocabulary terms used to describe nodes in the tree.
  *
- * @return
- *
+ * @return 
+ *  Array of vocab info or FALSE on failure.
+ * 
  * @ingroup tripal_phylotree_api
  */
 function tripal_phylogeny_get_node_types_vocab() {
-  // Get the vocabulary terms used to describe nodes in the tree
+  // Get the vocabulary terms used to describe nodes in the tree.
   $values = array(
     'name' => 'phylo_leaf',
     'cv_id' => array(
@@ -839,7 +843,7 @@ function tripal_phylogeny_import_tree_file($file_name, $format, $options = array
     }
   }
 
-  // get the phylotree record.
+  // Get the phylotree record.
   $values = array('phylotree_id' => $options['phylotree_id']);
   $phylotree = chado_generate_var('phylotree', $values);
 
@@ -862,7 +866,7 @@ function tripal_phylogeny_import_tree_file($file_name, $format, $options = array
       module_load_include('inc', 'tripal_phylogeny', 'includes/parsers/tripal_phylogeny.newick_parser');
       $tree = tripal_phylogeny_parse_newick_file($file_name);
 
-      // Assign the right and left indecies to the tree ndoes
+      // Assign the right and left indecies to the tree ndoes.
       tripal_assign_phylogeny_tree_indices($tree);
     }
     // Iterate through the tree nodes and add them to Chado in accordance
@@ -873,4 +877,4 @@ function tripal_phylogeny_import_tree_file($file_name, $format, $options = array
     $transaction->rollback();
     watchdog_exception('tripal_phylogeny', $e);
   }
-}
+}

tripal_chado/api/modules/tripal_chado.pub.api.inc

@@ -13,36 +13,38 @@
 
 
 /**
- * Retrieves a chado publication array
+ * Retrieves a chado publication array.
  *
  * @param $identifier
  *   An array used to uniquely identify a publication. This array has the same
  *   format as that used by the chado_generate_var(). The following keys can be
  *   useful for uniquely identifying a publication as they should be unique:
- *    - pub_id: the chado pub.pub_id primary key
- *    - nid: the drupal nid of the publication
- *    - uniquename: A value to matach with the pub.uniquename field
+ *    - pub_id: the chado pub.pub_id primary key.
+ *    - nid: the drupal nid of the publication.
+ *    - uniquename: A value to matach with the pub.uniquename field.
  *   There are also some specially handled keys. They are:
  *    - property: An array describing the property to select records for. It
  *      should at least have either a 'type_name' key (if unique across cvs) or
- *      'type_id' key. Other supported keys include: 'cv_id', 'cv_name' (of the type),
- *      'value' and 'rank'
- *    - dbxref: The database cross reference accession.  It should be in the form
- *        DB:ACCESSION, where DB is the database name and ACCESSION is the
- *        unique publication identifier (e.g. PMID:4382934)
+ *      'type_id' key. Other supported keys include: 'cv_id', 'cv_name' 
+ *      (of the type), 'value' and 'rank'
+ *    - dbxref: The database cross reference accession.  It should be in the 
+ *      form DB:ACCESSION, where DB is the database name and ACCESSION is the
+ *      unique publication identifier (e.g. PMID:4382934)
  *    - dbxref_id:  The dbxref.dbxref_id of the publication.
  * @param $options
  *   An array of options. Supported keys include:
- *     - Any keys supported by chado_generate_var(). See that function definition for
- *       additional details.
+ *     - Any keys supported by chado_generate_var(). See that function 
+ *       definition for additional details.
  *
- * NOTE: the $identifier parameter can really be any array similar to $values passed into
- *   chado_select_record(). It should fully specify the pub record to be returned.
+ * NOTE: the $identifier parameter can really be any array similar to $values 
+ * passed into chado_select_record(). It should fully specify the pub record to 
+ * be returned.
  *
  * @return
- *   If a singe publication is retreived using the identifiers, then a publication
- *   array will be returned.  The array is of the same format returned by the
- *   chado_generate_var() function. Otherwise, FALSE will be returned.
+ *   If a singe publication is retreived using the identifiers, then a 
+ *   publication array will be returned.  The array is of the same format 
+ *   returned by the chado_generate_var() function. Otherwise, FALSE will be 
+ *   returned.
  *
  * @ingroup tripal_pub_api
  */
@@ -65,7 +67,8 @@ function tripal_get_publication($identifiers, $options = array()) {
     );
   }
 
-  // If one of the identifiers is property then use chado_get_record_with_property()
+  // If one of the identifiers is property then use 
+  // chado_get_record_with_property().
   if (array_key_exists('property', $identifiers)) {
     $property = $identifiers['property'];
     unset($identifiers['property']);
@@ -105,11 +108,11 @@ function tripal_get_publication($identifiers, $options = array()) {
     }
   }
   elseif (array_key_exists('dbxref_id', $identifiers)) {
-    // first get the pub_dbxref record
+    // First get the pub_dbxref record.
     $values = array('dbxref_id' => $identifiers['dbxref_id']);
     $pub_dbxref = chado_select_record('pub_dbxref', array('pub_id'), $values);
 
-    // now get the pub
+    // Now get the pub.
     if (count($pub_dbxref) > 0) {
       $pub = chado_generate_var('pub', array('pub_id' => $pub_dbxref[0]->pub_id), $options);
     }
@@ -118,13 +121,14 @@ function tripal_get_publication($identifiers, $options = array()) {
     }
 
   }
-  // Else we have a simple case and we can just use chado_generate_var to get the pub
+  // Else we have a simple case and we can just use chado_generate_var to get 
+  // the pub.
   else {
-    // Try to get the pub
+    // Try to get the pub.
     $pub = chado_generate_var('pub', $identifiers, $options);
   }
 
-  // Ensure the pub is singular. If it's an array then it is not singular
+  // Ensure the pub is singular. If it's an array then it is not singular.
   if (is_array($pub)) {
     tripal_report_error('tripal_pub_api', TRIPAL_ERROR,
       "chado_get_publication: The identifiers did not find a single unique record. Identifiers passed: %identifier.",
@@ -132,7 +136,7 @@ function tripal_get_publication($identifiers, $options = array()) {
     );
   }
 
-  // Report an error if $pub is FALSE since then chado_generate_var has failed
+  // Report an error if $pub is FALSE since then chado_generate_var has failed.
   elseif ($pub === FALSE) {
     tripal_report_error('tripal_pub_api', TRIPAL_ERROR,
       "chado_get_publication: Could not find a publication using the identifiers
@@ -159,26 +163,31 @@ function tripal_get_publication($identifiers, $options = array()) {
  * @param $pub_details
  *   An associative array with details about the publications. The expected keys
  *   are:
- *     'Title':              The title of the publication
- *     'Year':               The published year of the publication
- *     'Publication Type':   An array of publication types. A publication can have more than one type.
- *     'Series Name':        The series name of the publication
- *     'Journal Name':       An alternative to 'Series Name'
- *     'Conference Name':    An alternative to 'Series Name'
- *     'Citation':           The publication citation (this is the value saved in the pub.uniquename field and must be unique)
- *   If this key is present it will also be checked
- *     'Publication Dbxref': A database cross reference of the form DB:ACCESSION where DB is the name
- *                           of the database and ACCESSION is the unique identifier (e.g PMID:3483139)
+ *     'Title':              The title of the publication.
+ *     'Year':               The published year of the publication.
+ *     'Publication Type':   An array of publication types. A publication can 
+ *                           have more than one type.
+ *     'Series Name':        The series name of the publication.
+ *     'Journal Name':       An alternative to 'Series Name'.
+ *     'Conference Name':    An alternative to 'Series Name'.
+ *     'Citation':           The publication citation (this is the value saved 
+ *                           in the pub.uniquename field and must be unique).
+ *   
+ *     If this key is present it will also be checked
+ *     'Publication Dbxref': A database cross reference of the form DB:ACCESSION 
+ *                           where DB is the name of the database and ACCESSION 
+ *                           is the unique identifier (e.g PMID:3483139).
  *
  * @return
  *   An array containing the pub_id's of matching publications. Returns an
- *   empty array if no pubs match
+ *   empty array if no pubs match.
  *
  * @ingroup tripal_pub_api
  */
 function tripal_publication_exists($pub_details) {
 
-  // first try to find the publication using the accession number if that key exists in the details array
+  // First try to find the publication using the accession number if that key 
+  // exists in the details array.
   if (array_key_exists('Publication Dbxref', $pub_details)) {
     $pub = tripal_get_publication(array('dbxref' => $pub_details['Publication Dbxref']));
     if($pub) {
@@ -186,7 +195,7 @@ function tripal_publication_exists($pub_details) {
     }
   }
 
-  // make sure the citation is unique
+  // Make sure the citation is unique.
   if (array_key_exists('Citation', $pub_details)) {
     $pub = tripal_get_publication(array('uniquename' => $pub_details['Citation']));
     if($pub) {
@@ -194,7 +203,7 @@ function tripal_publication_exists($pub_details) {
     }
   }
 
-  // get the publication type (use the first publication type)
+  // Get the publication type (use the first publication type).
   if (array_key_exists('Publication Type', $pub_details)) {
     $type_name = '';
     if(is_array($pub_details['Publication Type'])) {
@@ -224,7 +233,8 @@ function tripal_publication_exists($pub_details) {
     return array();
   }
 
-  // get the series name.  The pub.series_name field is only 255 chars so we must truncate to be safe
+  // Get the series name.  The pub.series_name field is only 255 chars so we 
+  // must truncate to be safe.
   $series_name = '';
   if (array_key_exists('Series Name', $pub_details)) {
     $series_name = substr($pub_details['Series Name'], 0, 255);
@@ -236,7 +246,8 @@ function tripal_publication_exists($pub_details) {
     $series_name = substr($pub_details['Conference Name'], 0, 255);
   }
 
-  // make sure the publication is unique using the prefereed import duplication check
+  // Make sure the publication is unique using the prefereed import 
+  // duplication check.
   $import_dups_check = variable_get('tripal_pub_import_duplicate_check', 'title_year_media');
   $pubs = array();
   switch ($import_dups_check) {
@@ -280,12 +291,12 @@ function tripal_publication_exists($pub_details) {
  * @param $field
  *   The field in the publication to search on.
  * @param $string
- *   The string to search for
+ *   The string to search for.
  *
  * @return
- *   A json array of terms that begin with the provided string
+ *   A json array of terms that begin with the provided string.
  *
- * @ingroup tripal_chado_api
+ * @ingroup tripal_pub_api
  */
 function tripal_autocomplete_pub($string = '') {
   $items = array();
@@ -321,7 +332,7 @@ function tripal_autocomplete_pub($string = '') {
  *   If set to TRUE then the publication will be updated if it already exists
  *   in the database.
  *
- * @ingroup tripal_pub
+ * @ingroup tripal_pub_api
  */
 function tripal_import_pub_by_dbxref($pub_dbxref, $do_contact = FALSE, $do_update = TRUE) {
   $num_to_retrieve = 1;
@@ -366,11 +377,12 @@ function tripal_import_pub_by_dbxref($pub_dbxref, $do_contact = FALSE, $do_updat
     // is enabled. If so, then sync the nodes.
     if (module_exists('tripal_pub')) {
 
-      // sync the newly added publications with Drupal
+      // Sync the newly added publications with Drupal.
       print "Syncing publications with Drupal...\n";
       chado_node_sync_records('pub');
 
-      // if any of the importers wanted to create contacts from the authors then sync them
+      // If any of the importers wanted to create contacts from the authors 
+      // then sync them.
       if($do_contact) {
         print "Syncing contacts with Drupal...\n";
         chado_node_sync_records('contact');
@@ -391,12 +403,12 @@ function tripal_import_pub_by_dbxref($pub_dbxref, $do_contact = FALSE, $do_updat
  *
  * @param $report_email
  *   A list of email address, separated by commas, that should be notified
- *   once importing has completed
+ *   once importing has completed.
  * @param $do_update
  *   If set to TRUE then publications that already exist in the Chado database
- *   will be updated, whereas if FALSE only new publications will be added
+ *   will be updated, whereas if FALSE only new publications will be added.
  *
- * @ingroup tripal_pub
+ * @ingroup tripal_pub_api
  */
 function tripal_execute_active_pub_importers($report_email = FALSE, $do_update = FALSE) {
   $num_to_retrieve = 100;
@@ -410,7 +422,7 @@ function tripal_execute_active_pub_importers($report_email = FALSE, $do_update =
   $transaction = db_transaction();
 
   try {
-    // get all of the loaders
+    // Get all of the loaders.
     $args = array();
     $sql = "SELECT * FROM {tripal_pub_import} WHERE disabled = 0 ";
     $results = db_query($sql, $args);
@@ -419,27 +431,27 @@ function tripal_execute_active_pub_importers($report_email = FALSE, $do_update =
     foreach ($results as $import) {
       $page = 0;
       print "Executing importer: '" . $import->name . "'\n";
-      // keep track if any of the importers want to create contacts from authors
+      // Keep track if any of the importers want to create contacts from authors.
       if ($import->do_contact == 1) {
         $do_contact = TRUE;
       }
       $criteria = unserialize($import->criteria);
       $remote_db = $criteria['remote_db'];
       do {
-        // retrieve the pubs for this page. We'll retreive 100 at a time
+        // Retrieve the pubs for this page. We'll retreive 100 at a time.
         $results = tripal_get_remote_pubs($remote_db, $criteria, $num_to_retrieve, $page);
         $pubs = $results['pubs'];
         $reports[$import->name] = tripal_pub_add_publications($pubs, $import->do_contact, $do_update);
         $page++;
       }
-      // continue looping until we have a $pubs array that does not have
-      // our requested numer of records.  This means we've hit the end
+      // Continue looping until we have a $pubs array that does not have
+      // our requested numer of records.  This means we've hit the end.
       while (count($pubs) == $num_to_retrieve);
     }
 
-    // sync the newly added publications with Drupal. If the user
+    // Sync the newly added publications with Drupal. If the user
     // requested a report then we don't want to print any syncing information
-    // so pass 'FALSE' to the sync call
+    // so pass 'FALSE' to the sync call.
     // For backwards compatibility check to see if the legacy pub module
     // is enabled. If so, then sync the nodes.
     if (module_exists('tripal_pub')) {
@@ -447,7 +459,8 @@ function tripal_execute_active_pub_importers($report_email = FALSE, $do_update =
       chado_node_sync_records('pub');
     }
 
-    // iterate through each of the reports and generate a final report with HTML links
+    // Iterate through each of the reports and generate a final report with HTML
+    // links.
     $HTML_report = '';
     if ($report_email) {
       $HTML_report .= "<html>";
@@ -475,7 +488,8 @@ function tripal_execute_active_pub_importers($report_email = FALSE, $do_update =
     // For backwards compatibility check to see if the legacy pub module
     // is enabled. If so, then sync the nodes.
     if (module_exists('tripal_pub')) {
-      // if any of the importers wanted to create contacts from the authors then sync them
+      // If any of the importers wanted to create contacts from the authors then 
+      // sync them.
       if($do_contact) {
         print "Syncing contacts with Drupal...\n";
         chado_node_sync_records('contact');
@@ -512,7 +526,7 @@ function tripal_execute_active_pub_importers($report_email = FALSE, $do_update =
  *   no dbxref then all of the publications currently in the Chado database
  *   for this remote database will be updated.
  *
- * @ingroup tripal_pub
+ * @ingroup tripal_pub_api
  */
 function tripal_reimport_publications($do_contact = FALSE, $dbxref = NULL, $db = NULL) {
 
@@ -522,7 +536,8 @@ function tripal_reimport_publications($do_contact = FALSE, $dbxref = NULL, $db =
   $transaction = db_transaction();
   try {
 
-    // get a list of all publications by their Dbxrefs that have supported databases
+    // Get a list of all publications by their Dbxrefs that have supported 
+    // databases.
     $sql = "
       SELECT DB.name as db_name, DBX.accession
       FROM pub P
@@ -546,17 +561,17 @@ function tripal_reimport_publications($do_contact = FALSE, $dbxref = NULL, $db =
     $results = chado_query($sql, $args);
 
     $num_to_retrieve = 100;
-    $i = 0;                 // count the number of IDs. When we hit $num_to_retrieve we'll do the query
-    $curr_db = '';          // keeps track of the current current database
-    $ids = array();         // the list of IDs for the database
-    $search = array();      // the search array passed to the search function
+    $i = 0;                 // count the number of IDs. When we hit $num_to_retrieve we'll do the query.
+    $curr_db = '';          // keeps track of the current current database.
+    $ids = array();         // the list of IDs for the database.
+    $search = array();      // the search array passed to the search function.
 
-    // iterate through the pub IDs
+    // Iterate through the pub IDs.
     while ($pub = $results->fetchObject()) {
       $accession = $pub->accession;
       $remote_db = $pub->db_name;
 
-      // here we need to only update publications for databases we support
+      // Here we need to only update publications for databases we support.
       $supported_dbs = variable_get('tripal_pub_supported_dbs', array());
       if(!in_array($remote_db, $supported_dbs)) {
         continue;
@@ -582,11 +597,11 @@ function tripal_reimport_publications($do_contact = FALSE, $dbxref = NULL, $db =
     // For backwards compatibility check to see if the legacy pub module
     // is enabled. If so, then sync the nodes.
     if (module_exists('tripal_pub')) {
-      // sync the newly added publications with Drupal
+      // Sync the newly added publications with Drupal.
       print "Syncing publications with Drupal...\n";
       chado_node_sync_records('pub');
 
-      // if the caller wants to create contacts then we should sync them
+      // If the caller wants to create contacts then we should sync them.
       if ($do_contact) {
         print "Syncing contacts with Drupal...\n";
         chado_node_sync_records('contact');
@@ -613,10 +628,10 @@ function tripal_reimport_publications($do_contact = FALSE, $dbxref = NULL, $db =
  * @param $options
  *  Options pertaining to what publications to generate citations for.
  *  One of the following must be present:
- *   - all: Create and replace citation for all pubs
- *   - new: Create citation for pubs that don't already have one
+ *   - all: Create and replace citation for all pubs.
+ *   - new: Create citation for pubs that don't already have one.
  *
- * @ingroup tripal_pub
+ * @ingroup tripal_pub_api
  */
 function tripal_pub_create_citations($options) {
   $skip_existing = TRUE;
@@ -629,12 +644,12 @@ function tripal_pub_create_citations($options) {
   ";
   $citation_type_id = chado_query($sql)->fetchField();
 
-  // Create and replace citation for all pubs
+  // Create and replace citation for all pubs.
   if ($options == 'all') {
     $sql = "SELECT pub_id FROM {pub} P WHERE pub_id <> 1";
     $skip_existing = FALSE;
   }
-  // Create citation for pubs that don't already have one
+  // Create citation for pubs that don't already have one.
   else if ($options == 'new') {
     $sql = "
       SELECT pub_id
@@ -656,7 +671,8 @@ function tripal_pub_create_citations($options) {
     if ($pub_arr) {
       $citation = tripal_pub_create_citation($pub_arr);
       print $citation . "\n\n";
-      // Replace if citation exists. This condition is never TRUE if $skip_existing is TRUE
+      // Replace if citation exists. This condition is never TRUE if 
+      // $skip_existing is TRUE.
       if ($pub_arr['Citation']) {
         $sql = "
           UPDATE {pubprop} SET value = :value
@@ -665,7 +681,7 @@ function tripal_pub_create_citations($options) {
         chado_query($sql, array(':value' => $citation, ':pub_id' => $pub->pub_id,
           ':type_id' => $citation_type_id, ':rank' => 0));
         $counter_updated ++;
-        // Generate a new citation
+        // Generate a new citation.
       } else {
         $sql = "
           INSERT INTO {pubprop} (pub_id, type_id, value, rank)
@@ -692,21 +708,23 @@ function tripal_pub_create_citations($options) {
  *   are the publication ontology term names and values are the
  *   corresponding details.  The pub array can contain the following
  *   keys with corresponding values:
- *     - Publication Type:  an array of publication types. a publication can have more than one type
- *     - Authors: a  string containing all of the authors of a publication
- *     - Journal Name:  a string containing the journal name
- *     - Journal Abbreviation: a string containing the journal name abbreviation
- *     - Series Name: a string containing the series (e.g. conference proceedings) name
+ *     - Publication Type:  an array of publication types. a publication can 
+ *       have more than one type.
+ *     - Authors: a  string containing all of the authors of a publication.
+ *     - Journal Name:  a string containing the journal name.
+ *     - Journal Abbreviation: a string containing the journal name abbreviation.
+ *     - Series Name: a string containing the series (e.g. conference 
+ *       proceedings) name.
  *     - Series Abbreviation: a string containing the series name abbreviation
- *     - Volume: the serives volume number
- *     - Issue: the series issue number
- *     - Pages: the page numbers for the publication
- *     - Publication Date:  A date in the format "Year Month Day"
+ *     - Volume: the serives volume number.
+ *     - Issue: the series issue number.
+ *     - Pages: the page numbers for the publication.
+ *     - Publication Date:  A date in the format "Year Month Day".
  *
  * @return
- *   A text string containing the citation
+ *   A text string containing the citation.
  *
- * @ingroup tripal_pub
+ * @ingroup tripal_pub_api
  */
 function tripal_pub_create_citation($pub) {
   $citation = '';
@@ -745,8 +763,8 @@ function tripal_pub_create_citation($pub) {
       }
       else if ($ptype == "Research Support, Non-U.S. Gov't") {
         $pub_type = $ptype;
-        // we don't break because if the article is also a Journal Article
-        // we prefer that type
+        // We don't break because if the article is also a Journal Article
+        // we prefer that type.
       }
     }
     // If we don't have a recognized publication type, then just use the
@@ -999,14 +1017,16 @@ function tripal_pub_create_citation($pub) {
  * Retrieves the minimal information to uniquely describe any publication.
  *
  * The returned array is an associative array where the keys are
- * the controlled vocabulary terms in the form [vocab]:[accession]
+ * the controlled vocabulary terms in the form [vocab]:[accession].
  *
  * @param $pub
- *   A publication object as created by chado_generate_var()
+ *   A publication object as created by chado_generate_var().
  *
  * @return
  *   An array with the following keys:  'Citation', 'Abstract', 'Authors',
  *   'URL'. All keys are term names in the Tripal Publication Ontology :TPUB.
+ * 
+ * @ingroup tripal_pub_api
  */
 function tripal_get_minimal_pub_info($pub) {
   if (!$pub) {
@@ -1018,11 +1038,11 @@ function tripal_get_minimal_pub_info($pub) {
     return array();
   }
 
-  // expand the title
+  // Expand the title.
   $pub = chado_expand_var($pub, 'field', 'pub.title');
   $pub = chado_expand_var($pub, 'field', 'pub.volumetitle');
 
-  // get the abstract
+  // Get the abstract.
   $values = array(
     'pub_id' => $pub->pub_id,
     'type_id' => array(
@@ -1058,7 +1078,7 @@ function tripal_get_minimal_pub_info($pub) {
     $authors_list = $authors->value;
   }
 
-  // get the first database cross-reference with a url.
+  // Get the first database cross-reference with a url.
   $options = array('return_array' => 1);
   $pub = chado_expand_var($pub, 'table', 'pub_dbxref', $options);
   $dbxref = NULL;
@@ -1070,7 +1090,7 @@ function tripal_get_minimal_pub_info($pub) {
     }
   }
 
-  // get the URL.
+  // Get the URL.
   $values = array(
     'pub_id' => $pub->pub_id,
     'type_id' => array(
@@ -1103,7 +1123,7 @@ function tripal_get_minimal_pub_info($pub) {
     $dbxrefs[] = $pub_dbxref->dbxref_id->db_id->name . ':' . $pub_dbxref->dbxref_id->accession;
   }
 
-  // get the citation
+  // Get the citation.
   $values = array(
     'pub_id' => $pub->pub_id,
     'type_id' => array(

tripal_chado/api/modules/tripal_chado.stock.api.inc

@@ -15,38 +15,40 @@
  * Retrieves a chado stock variable
  *
  * @param $identifier
- *   An array with the key stating what the identifier is. Supported keys (only one of the
- *   following unique keys is required):
+ *   An array with the key stating what the identifier is. Supported keys (only 
+ *   one of the following unique keys is required):
  *    - stock_id: the chado stock.stock_id primary key
  *    - nid: the drupal nid of the stock
  *   There are also some specially handled keys. They are:
- *    - property: An array/object describing the property to select records for. It
- *      should at least have either a type_name (if unique across cvs) or type_id. Other
- *      supported keys include: cv_id/cv_name (of the type), value and rank
+ *    - property: An array/object describing the property to select records for. 
+ *      It should at least have either a type_name (if unique across cvs) or 
+ *      type_id. Other supported keys include: cv_id/cv_name (of the type), 
+ *      value and rank
  * @param $options
  *   An array of options. Supported keys include:
- *     - Any keys supported by chado_generate_var(). See that function definition for
- *       additional details.
+ *     - Any keys supported by chado_generate_var(). See that function 
+ *      definition for additional details.
  *
- * NOTE: the $identifier parameter can really be any array similar to $values passed into
- *   chado_select_record(). It should fully specify the stock record to be returned.
+ * NOTE: the $identifier parameter can really be any array similar to $values
+ * passed into chado_select_record(). It should fully specify the stock record 
+ * to be returned.
  *
  * @return
- *   If unique values were passed in as an identifier then an object describing the stock
- *   will be returned (will be a chado variable from chado_generate_var()). Otherwise,
- *   FALSE will be returned.
+ *   If unique values were passed in as an identifier then an object describing 
+ *   the stock will be returned (will be a chado variable from 
+ *   chado_generate_var()). Otherwise, FALSE will be returned.
  *
  * @ingroup tripal_stock_api
  */
 function tripal_get_stock($identifiers, $options = array()) {
 
-  // Set Defaults
+  // Set Defaults.
   if (!isset($options['include_fk'])) {
-    // Tells chado_generate_var to only expand 1 level
+    // Tells chado_generate_var to only expand 1 level.
     $options['include_fk'] = array('type_id' => TRUE, 'dbxref_id' => TRUE);
   }
 
-  // Error Checking of parameters
+  // Error Checking of parameters.
   if (!is_array($identifiers)) {
     tripal_report_error(
       'tripal_stock_api',
@@ -71,7 +73,8 @@ function tripal_get_stock($identifiers, $options = array()) {
     );
   }
 
-  // If one of the identifiers is property then use chado_get_record_with_property()
+  // If one of the identifiers is property then use 
+  // chado_get_record_with_property().
   if (isset($identifiers['property'])) {
     $property = $identifiers['property'];
     unset($identifiers['property']);
@@ -82,10 +85,11 @@ function tripal_get_stock($identifiers, $options = array()) {
     );
   }
 
-  // Else we have a simple case and we can just use chado_generate_var to get the stock
+  // Else we have a simple case and we can just use chado_generate_var to get 
+  // the stock.
   else {
 
-    // Try to get the stock
+    // Try to get the stock.
     $stock = chado_generate_var(
       'stock',
       $identifiers,
@@ -93,7 +97,7 @@ function tripal_get_stock($identifiers, $options = array()) {
     );
   }
 
-  // Ensure the stock is singular. If it's an array then it is not singular
+  // Ensure the stock is singular. If it's an array then it is not singular.
   if (is_array($stock)) {
     tripal_report_error(
       'tripal_stock_api',
@@ -105,7 +109,7 @@ function tripal_get_stock($identifiers, $options = array()) {
     );
   }
 
-  // Report an error if $stock is FALSE since then chado_generate_var has failed
+  // Report an error if $stock is FALSE since then chado_generate_var has failed.
   elseif ($stock === FALSE) {
     tripal_report_error(
       'tripal_stock_api',
@@ -126,16 +130,16 @@ function tripal_get_stock($identifiers, $options = array()) {
 }
 
 /**
- * Retrieves a chado stock variable
+ * Retrieves a chado stock variable.
  *
  * @param $identifier
- *   An array with the key stating what the identifier is. Supported keys include any
- *   field in the stock table. See the chado_select_record() $values parameter for
- *   additional details including an example.
+ *   An array with the key stating what the identifier is. Supported keys 
+ *   include any field in the stock table. See the chado_select_record() $values
+ *   parameter for additional details including an example.
  * @param $options
  *   An array of options. Supported keys include:
- *     - Any keys supported by chado_generate_var(). See that function definition for
- *       additional details.
+ *     - Any keys supported by chado_generate_var(). See that function 
+ *       definition for additional details.
  *
  * @return
  *   An array of stock objects matching the criteria.
@@ -144,13 +148,13 @@ function tripal_get_stock($identifiers, $options = array()) {
  */
 function tripal_get_multiple_stocks($identifiers, $options = array()) {
 
-  // Set Defaults
+  // Set Defaults.
   if (!isset($options['include_fk'])) {
-    // Tells chado_generate_var to only expand 1 level
+    // Tells chado_generate_var to only expand 1 level.
     $options['include_fk'] = array('type_id' => TRUE, 'dbxref_id' => TRUE);
   }
 
-  // Error Checking of parameters
+  // Error Checking of parameters.
   if (!is_array($identifiers)) {
     tripal_report_error(
       'tripal_stock_api',
@@ -175,7 +179,8 @@ function tripal_get_multiple_stocks($identifiers, $options = array()) {
     );
   }
 
-  // If one of the identifiers is property then use chado_get_record_with_property()
+  // If one of the identifiers is property then use 
+  // chado_get_record_with_property().
   if (isset($identifiers['property'])) {
     $property = $identifiers['property'];
     unset($identifiers['property']);
@@ -186,10 +191,11 @@ function tripal_get_multiple_stocks($identifiers, $options = array()) {
     );
   }
 
-  // Else we have a simple case and we can just use chado_generate_var to get the stock
+  // Else we have a simple case and we can just use chado_generate_var to get 
+  //the stock.
   else {
 
-    // Try to get the stock
+    // Try to get the stock.
     $stock = chado_generate_var(
       'stock',
       $identifiers,
@@ -197,7 +203,7 @@ function tripal_get_multiple_stocks($identifiers, $options = array()) {
     );
   }
 
-  // Report an error if $stock is FALSE since then chado_generate_var has failed
+  // Report an error if $stock is FALSE since then chado_generate_var has failed.
   if ($stock === FALSE) {
     tripal_report_error(
       'tripal_stock_api',

tripal_chado/api/tripal_chado.api.inc

@@ -1,6 +1,20 @@
 <?php
 
+/**
+ * @file
+ *
+ * This file provides the Chado API: a set of functions for
+ * interacting with Chado.
+ */
 
+/**
+ * @defgroup tripal_chado_api Chado
+ *
+ * @ingroup tripal_api
+ * The Tripal Chado API: a set of functions for
+ * interacting with Chado.
+ *
+ */
 /**
  * Publishes content in Chado as a new TripalEntity entity.
  *
@@ -251,6 +265,8 @@ function tripal_chado_publish_records($values, $job_id = NULL) {
  *    The name of a base table in Chado.
  * @return
  *    An array of tokens where the key is the machine_name of the token.
+ * 
+ * @ingroup tripal_chado_api
  */
 function tripal_get_chado_tokens($base_table) {
 
@@ -307,6 +323,8 @@ function tripal_get_chado_tokens($base_table) {
  *
  * @return
  *   The string will all tokens replaced with values.
+ * 
+ *  @ingroup tripal_chado_api
  */
 function tripal_replace_chado_tokens($string, $record) {
   // Get the list of tokens

tripal_chado/api/tripal_chado.custom_tables.api.inc

@@ -17,9 +17,9 @@
  * using the Drupal Schema API array.
  *
  * @param $table_id
- *   The table_id of the table to edit
+ *   The table_id of the table to edit.
  * @param $table_name
- *   The name of the custom table
+ *   The name of the custom table.
  * @param $schema
  *   Use the Schema API array to define the custom table.
  * @param $skip_if_exists
@@ -33,32 +33,32 @@ function chado_edit_custom_table($table_id, $table_name, $schema, $skip_if_exist
 
   $transaction = db_transaction();
   try {
-    // Create a new record
+    // Create a new record.
     $record = new stdClass();
     $record->table_id = $table_id;
     $record->table_name = $table_name;
     $record->schema = serialize($schema);
 
-    // get the current custom table record
+    // Get the current custom table record.
     $sql = "SELECT * FROM {tripal_custom_tables} WHERE table_id = :table_id";
     $results = db_query($sql, array(':table_id' => $table_id));
     $custom_table = $results->fetchObject();
 
-    // if this is a materialized view then don't allow editing with this function
+    // If this is a materialized view then don't allow editing with this function.
     if ($custom_table->mview_id) {
       tripal_report_error('tripal_chado', TRIPAL_ERROR, "Please use the tripal_edit_mview() function to edit this custom table as it is a materialized view.", array());
       drupal_set_message("This custom table is a materialized view. Please use the "  . l('Materialized View', 'admin/tripal/storage/chado/mviews') . " interface to edit it.", 'error');
       return FALSE;
     }
 
-    // if the user changed the table name, we want to drop the old one and force
+    // If the user changed the table name, we want to drop the old one and force
     // creation of the new one.
     if ($custom_table->table_name != $table_name) {
       chado_query("DROP TABLE %s", $custom_table->table_name);
       $skip_if_exists = 0; // we want to create the table
     }
 
-    // if skip creation is not set, then drop the table from chado if it exists
+    // If skip creation is not set, then drop the table from chado if it exists.
     if (!$skip_if_exists) {
       if (db_table_exists($custom_table->table_name)) {
         chado_query("DROP TABLE %s", $custom_table->table_name);
@@ -66,7 +66,7 @@ function chado_edit_custom_table($table_id, $table_name, $schema, $skip_if_exist
       }
     }
 
-    // update the custom table record and run the create custom table function
+    // Update the custom table record and run the create custom table function.
     drupal_write_record('tripal_custom_tables', $record, 'table_id');
     $success = chado_create_custom_table ($table_name, $schema, $skip_if_exists);
 
@@ -96,8 +96,8 @@ function chado_edit_custom_table($table_id, $table_name, $schema, $skip_if_exist
  * added to the tripal_custom_tables and no table is created in Chado.
  *
  * If you are creating a materialized view do not use this function, but rather
- * use the tripal_add_mview(). A materialized view is also considered a custom table
- * and an entry for it will be added to both the tripal_mviews and
+ * use the tripal_add_mview(). A materialized view is also considered a custom 
+ * table and an entry for it will be added to both the tripal_mviews and
  * tripal_custom_tables tables, but only if the tripal_add_mview() function is
  * used. The optional $mview_id parameters in this function is intended
  * for use by the tripal_add_mview() function when it calls this function
@@ -106,7 +106,7 @@ function chado_edit_custom_table($table_id, $table_name, $schema, $skip_if_exist
  * @param $table
  *   The name of the table to create.
  * @param $schema
- *   A Drupal-style Schema API definition of the table
+ *   A Drupal-style Schema API definition of the table.
  * @param $skip_if_exists
  *   Set as TRUE to skip dropping and re-creation of the table if it already
  *   exists.  This is useful if the table was already created through another
@@ -122,7 +122,7 @@ function chado_edit_custom_table($table_id, $table_name, $schema, $skip_if_exist
  *   admin pages. However, when called by Drush we don't want to redirect. This
  *   parameter allows this to be used as a true API function.
  * @return
- *   TRUE on success, FALSE on failure
+ *   TRUE on success, FALSE on failure.
  *
  * @ingroup tripal_custom_tables_api
  */
@@ -138,27 +138,28 @@ function chado_create_custom_table($table, $schema, $skip_if_exists = TRUE,
 
   $transaction = db_transaction();
   try {
-    // see if the table entry already exists in the tripal_custom_tables table.
+    // See if the table entry already exists in the tripal_custom_tables table.
     $sql = "SELECT * FROM {tripal_custom_tables} WHERE table_name = :table_name";
     $results = db_query($sql, array(':table_name' => $table));
     $centry = $results->fetchObject();
 
-    // check to see if the table already exists in the chado schema
+    // Check to see if the table already exists in the chado schema.
     $exists = chado_table_exists($table);
 
-    // if the table does not exist then create it
+    // If the table does not exist then create it.
     if (!$exists) {
       $ret = db_create_table($chado_dot . $table, $schema);
       $created = 1;
     }
 
-    // if the table exists in Chado and in our custom table and
-    // skip creation is turned off then drop and re-create the table
+    // If the table exists in Chado and in our custom table and
+    // skip creation is turned off then drop and re-create the table.
     if ($exists and is_object($centry) and !$skip_if_exists) {
 
-      // drop the table we'll recreate it with the new schema
+      // Drop the table we'll recreate it with the new schema.
       chado_query('DROP TABLE {' . $table . '}');
-      // remove any 'referring_tables' from the array as the db_create_table doesn't use that
+      // Remove any 'referring_tables' from the array as the 
+      // db_create_table doesn't use that.
       $new_schema = $schema;
       if (array_key_exists('referring_tables', $new_schema)) {
         unset($new_schema['referring_tables']);
@@ -167,7 +168,7 @@ function chado_create_custom_table($table, $schema, $skip_if_exists = TRUE,
       $recreated = 1;
     }
 
-    // add an entry in the tripal_custom_table
+    // Add an entry in the tripal_custom_table.
     $record = new stdClass();
     $record->table_name = $table;
     $record->schema = serialize($schema);
@@ -175,17 +176,17 @@ function chado_create_custom_table($table, $schema, $skip_if_exists = TRUE,
       $record->mview_id = $mview_id;
     }
 
-    // if an entry already exists then remove it
+    // If an entry already exists then remove it.
     if ($centry) {
       $sql = "DELETE FROM {tripal_custom_tables} WHERE table_name = :table_name";
       db_query($sql, array(':table_name' => $table));
     }
     $success = drupal_write_record('tripal_custom_tables', $record);
 
-    // now add any foreign key constraints
+    // Now add any foreign key constraints.
     if (($created or !$skip_if_exists) and array_key_exists('foreign keys', $schema)) {
 
-      // iterate through the foreign keys and add each one
+      // Iterate through the foreign keys and add each one.
       $fkeys = $schema['foreign keys'];
       foreach ($fkeys as $fktable => $fkdetails) {
         $relations = $fkdetails['columns'];
@@ -201,7 +202,7 @@ function chado_create_custom_table($table, $schema, $skip_if_exists = TRUE,
       }
     }
 
-    // Add the custom table to the semantic web interface
+    // Add the custom table to the semantic web interface.
     tripal_add_chado_semweb_table($table);
   }
   catch (Exception $e) {
@@ -244,10 +245,10 @@ function chado_create_custom_table($table, $schema, $skip_if_exists = TRUE,
  * a user and needs validation.
  *
  * @param $schema_array
- *   the Drupal Schema API compatible array
+ *   the Drupal Schema API compatible array.
  *
  * @return
- *   An empty string for success or a message string for failure
+ *   An empty string for success or a message string for failure.
  *
  * @ingroup tripal_custom_tables_api
  */
@@ -263,7 +264,7 @@ function chado_validate_custom_table_schema($schema_array) {
   }
 
 
-  // check index length
+  // Check index length.
   if (array_key_exists('indexes', $schema_array)) {
     foreach ($schema_array['indexes'] as $index_name => $details) {
       if (strlen($schema_array['table'] . '_' . $index_name) > 60) {
@@ -275,7 +276,7 @@ function chado_validate_custom_table_schema($schema_array) {
     }
   }
 
-  // check unique key length
+  // Check unique key length.
   if (array_key_exists('unique keys', $schema_array)) {
     foreach ($schema_array['unique keys'] as $index_name => $details) {
       if (strlen($schema_array['table'] . '_' . $index_name) > 60) {
@@ -289,13 +290,13 @@ function chado_validate_custom_table_schema($schema_array) {
 
 }
 /**
- * Retrieve the custom table id given the name
+ * Retrieve the custom table id given the name.
  *
  * @param $table_name
- *   The name of the custom table
+ *   The name of the custom table.
  *
  * @return
- *   The unique identifier for the given table
+ *   The unique identifier for the given table.
  *
  * @ingroup tripal_custom_tables_api
  */
@@ -315,7 +316,7 @@ function chado_get_custom_table_id($table_name) {
 /**
  * Retrieves the list of custom tables in this site.
  *
- * @returns
+ * @return
  *   An associative array where the key and value pairs are the table names.
  *
  * @ingroup tripal_custom_tables_api
@@ -336,10 +337,10 @@ function chado_get_custom_table_names($include_mview = TRUE) {
   return $tables;
 }
 /**
- * Deletes the specified custom table
+ * Deletes the specified custom table.
  *
  * @param $table_id
- *   The unique ID of the custom table for the action to be performed on
+ *   The unique ID of the custom table for the action to be performed on.
  *
  * @ingroup tripal_custom_tables_api
  */
@@ -351,26 +352,26 @@ function chado_delete_custom_table($table_id) {
     return '';
   }
 
-  // get this table details
+  // Get this table details.
   $sql = "SELECT * FROM {tripal_custom_tables} WHERE table_id = :table_id";
   $results = db_query($sql, array(':table_id' => $table_id));
   $custom_table = $results->fetchObject();
 
-  // if this is a materialized view then don't allow deletion with this function
+  // If this is a materialized view then don't allow deletion with this function.
   if ($custom_table->mview_id) {
     tripal_report_error('tripal_chado', TRIPAL_ERROR, "Please use the tripal_delete_mview() function to delete this custom table as it is a materialized view. Table not deleted.", array());
     drupal_set_message("This custom table is a materialized view. Please use the "  . l('Materialized View', 'admin/tripal/storage/chado/mviews') . " interface to delete it.", 'error');
     return FALSE;
   }
 
-  // remove the entry from the tripal_custom tables table
+  // Remove the entry from the tripal_custom tables table.
   $sql = "DELETE FROM {tripal_custom_tables} WHERE table_id = $table_id";
   $success = db_query($sql);
   if ($success) {
     drupal_set_message(t("Custom Table '%name' removed", array('%name' => $custom_table->table_name)));
   }
 
-  // drop the table from chado if it exists
+  // Drop the table from chado if it exists.
   if (chado_table_exists($custom_table->table_name)) {
     $success = chado_query("DROP TABLE {" .  $custom_table->table_name . "}");
     if ($success) {

tripal_chado/api/tripal_chado.migrate.api.inc

@@ -1,4 +1,16 @@
 <?php 
+/**
+ * @file
+ * Provides an application programming interface (API) to migrate content.
+ */
+
+/**
+ * @defgroup tripal_chado_migrate_api Chado Entity
+ * @ingroup tripal_chado_api
+ * @{
+ * Provides an application programming interface (API) to migrate content.
+ * @}
+ */
 
 /**
  * Migrate Tripal content types
@@ -17,25 +29,25 @@
  *         'data_table' => $table
  *       )
  *     )
- * 
+ * @ingroup tripal_chado_migrate_api
  */
 function tripal_chado_migrate_tripal_content_type($type = array()) {
     
-  // Check if the term already exists
+  // Check if the term already exists.
   $term = tripal_load_term_entity($type);
-  // If term doesn't exist, create a new bundle for this term
+  // If term doesn't exist, create a new bundle for this term.
   if (!$term) {
     print("Creating bundle for term '" . $type['term_name'] . "'...\n");
     $success = tripal_create_bundle($type);
     $term = tripal_load_term_entity($type);
   }
-  // Create bundle name
+  // Create bundle name.
   $bundle_name = 'bio_data_' . $term->id;
     
-  // Publish records for the bundle
+  // Publish records for the bundle.
   $value = array(
     'sync_node' => 1,
     'bundle_name' => $bundle_name
   );
   tripal_chado_publish_records($value);
-}
+}

tripal_chado/api/tripal_chado.mviews.api.inc

@@ -1,16 +1,17 @@
 <?php
 /**
  * @file
- * Provides an application programming interface (API) to manage materialized views in Chado.
+ * Provides an application programming interface (API) to manage materialized 
+ * views in Chado.
  */
 
 /**
  * @defgroup tripal_mviews_api Chado Materalized Views
  * @ingroup tripal_chado_api
  * @{
- * Provides an application programming interface (API) to manage materialized views in Chado.
- * The Perl-based chado comes with an interface for managing materialzed views.  This
- * API provides an alternative Drupal-based method.
+ * Provides an application programming interface (API) to manage materialized 
+ * views in Chado The Perl-based chado comes with an interface for managing 
+ * materialzed views.  This API provides an alternative Drupal-based method.
  * @}
  */
 
@@ -24,15 +25,16 @@
  * @param $name
  *   The name of the materialized view.
  * @param $modulename
- *   The name of the module submitting the materialized view (e.g. 'tripal_library')
+ *   The name of the module submitting the materialized view 
+ *   (e.g. 'tripal_library').
  * @param $mv_schema
  *   If using the newer Schema API array to define the materialized view then
  *   this variable should contain the array or a string representation of the
  *   array.
  * @param $query
- *   The SQL query that loads the materialized view with data
+ *   The SQL query that loads the materialized view with data.
  * @param $comment
- *   A string containing a description of the materialized view
+ *   A string containing a description of the materialized view.
  * @param $redirect
  *   Optional (default: TRUE). By default this function redirects back to
  *   admin pages. However, when called by Drush we don't want to redirect. This
@@ -50,7 +52,7 @@ function tripal_add_mview($name, $modulename, $mv_schema, $query, $comment = NUL
 
   $mv_table = $mv_schema['table'];
 
-  // see if the mv_table name already exsists
+  // See if the mv_table name already exsists.
   $mview_id = db_query(
     'SELECT mview_id FROM {tripal_mviews} WHERE name = :name',
     array(':name' => $name))->fetchField();
@@ -58,7 +60,7 @@ function tripal_add_mview($name, $modulename, $mv_schema, $query, $comment = NUL
   if(!$mview_id) {
     $transaction = db_transaction();
     try {
-      // Create a new record
+      // Create a new record.
       $record = new stdClass();
       $record->name = $name;
       $record->modulename = $modulename;
@@ -66,21 +68,21 @@ function tripal_add_mview($name, $modulename, $mv_schema, $query, $comment = NUL
       $record->query = $query;
       $record->comment = $comment;
 
-      // convert the schema into a string format
+      // Convert the schema into a string format.
       $str_schema = var_export($mv_schema, TRUE);
       $str_schema = preg_replace('/=>\s+\n\s+array/', '=> array', $str_schema);
       $record->mv_schema = $str_schema;
 
-      // add the record to the tripal_mviews table and if successful
-      // create the new materialized view in the chado schema
+      // Add the record to the tripal_mviews table and if successful
+      // create the new materialized view in the chado schema.
       if (drupal_write_record('tripal_mviews', $record)) {
 
-        // drop the table from chado if it exists
+        // Drop the table from chado if it exists.
         if (chado_table_exists($mv_table)) {
           $sql = 'DROP TABLE {' . $mv_table . '}';
           chado_query($sql);
         }
-        // create the table
+        // Create the table.
         chado_create_custom_table($mv_table, $mv_schema, 0, $record->mview_id, $redirect);
       }
     }
@@ -102,30 +104,32 @@ function tripal_add_mview($name, $modulename, $mv_schema, $query, $comment = NUL
 }
 
 /**
- * Edits a materialized view to the chado database to help speed data access. This
- * function supports the older style where postgres column specifications
+ * Edits a materialized view to the chado database to help speed data access. 
+ * This function supports the older style where postgres column specifications
  * are provided using the $mv_table, $mv_specs and $indexed variables. It also
  * supports the newer preferred method where the materialized view is described
  * using the Drupal Schema API array.
  *
  * @param $mview_id
- *   The mview_id of the materialized view to edit
+ *   The mview_id of the materialized view to edit.
  * @param $name
  *   The name of the materialized view.
  * @param $modulename
- *   The name of the module submitting the materialized view (e.g. 'tripal_library')
+ *   The name of the module submitting the materialized view 
+ *   (e.g. 'tripal_library').
  * @param $mv_table
- *   The name of the table to add to chado. This is the table that can be queried.
+ *   The name of the table to add to chado. This is the table that can be 
+ *   queried.
  * @param $mv_specs
- *   The table definition
+ *   The table definition.
  * @param $indexed
- *   The columns that are to be indexed
+ *   The columns that are to be indexed.
  * @param $query
- *   The SQL query that loads the materialized view with data
+ *   The SQL query that loads the materialized view with data.
  * @param $special_index
- *   currently not used
+ *   currently not used.
  * @param $comment
- *   A string containing a description of the materialized view
+ *   A string containing a description of the materialized view.
  * @param $mv_schema
  *   If using the newer Schema API array to define the materialized view then
  *   this variable should contain the array.
@@ -202,13 +206,13 @@ function tripal_edit_mview($mview_id, $name, $modulename, $mv_table, $mv_specs,
 }
 
 /**
- * Retrieve the materialized view_id given the name
+ * Retrieve the materialized view_id given the name.
  *
  * @param $view_name
- *   The name of the materialized view
+ *   The name of the materialized view.
  *
  * @return
- *   The unique identifier for the given view
+ *   The unique identifier for the given view.
  *
  * @ingroup tripal_mviews_api
  */
@@ -231,7 +235,7 @@ function tripal_get_mview_id($view_name) {
  * @returns
  *   An associative array where the key and value pairs are the table names.
  *
- * @ingroup tripal_custom_tables_api
+ * @ingroup tripal_mviews_api
  */
 function chado_get_mview_table_names() {
 
@@ -248,10 +252,10 @@ function chado_get_mview_table_names() {
 }
 
 /**
- * Populates the specified Materialized View
+ * Populates the specified Materialized View.
  *
  * @param $mview_id
- *   The unique ID of the materialized view for the action to be performed on
+ *   The unique ID of the materialized view for the action to be performed on.
  *
  * @ingroup tripal_mviews_api
  */
@@ -262,12 +266,12 @@ function tripal_refresh_mview($mview_id) {
     return '';
   }
 
-  // get this mview details
+  // Get this mview details.
   $sql = "SELECT * FROM {tripal_mviews} WHERE mview_id = :mview_id";
   $results = db_query($sql, array(':mview_id' => $mview_id));
   $mview = $results->fetchObject();
 
-  // add a job to populate the mview
+  // Add a job to populate the mview.
   $args = array("$mview_id");
   tripal_add_job("Populate materialized view '$mview->name'", 'tripal_chado',
      'tripal_populate_mview', $args, $user->uid);
@@ -275,10 +279,10 @@ function tripal_refresh_mview($mview_id) {
 }
 
 /**
- * Retrieves the list of materialized view IDs and their names
+ * Retrieves the list of materialized view IDs and their names.
  *
  * @return
- *   An array of objects with the following properties:  mview_id, name
+ *   An array of objects with the following properties:  mview_id, name.
  *
  * @ingroup tripal_mviews_api
  *
@@ -297,12 +301,12 @@ function tripal_get_mviews() {
 }
 
 /**
- * Does the specified action for the specified Materialized View
+ * Does the specified action for the specified Materialized View.
  *
  * @param $op
- *   The action to be taken. One of update or delete
+ *   The action to be taken. One of update or delete.
  * @param $mview_id
- *   The unique ID of the materialized view for the action to be performed on
+ *   The unique ID of the materialized view for the action to be performed on.
  *
  * @ingroup tripal_mviews_api
  */
@@ -313,20 +317,20 @@ function tripal_delete_mview($mview_id) {
     return '';
   }
 
-  // get this mview details
+  // Get this mview details.
   $sql = "SELECT * FROM {tripal_mviews} WHERE mview_id = :mview_id";
   $results = db_query($sql, array(':mview_id' => $mview_id));
   $mview = $results->fetchObject();
 
-  // if op is to delete then do so
-  // remove the mview from the tripal_mviews table
+  // If op is to delete then do so.
+  // Remove the mview from the tripal_mviews table.
   $sql = "DELETE FROM {tripal_mviews} WHERE mview_id = $mview_id";
   db_query($sql);
 
-  // does the table already exist?
+  // Does the table already exist?
   $mview_exists = chado_table_exists($mview->mv_table);
 
-  // drop the table from chado if it exists
+  // Drop the table from chado if it exists.
   if ($mview_exists) {
     $sql = "DROP TABLE {" . $mview->mv_table . "}";
     $success = chado_query($sql);
@@ -340,13 +344,13 @@ function tripal_delete_mview($mview_id) {
 }
 
 /**
- * Update a Materialized View
+ * Update a Materialized View.
  *
  * @param $mview_id
- *   The unique identifier for the materialized view to be updated
+ *   The unique identifier for the materialized view to be updated.
  *
  * @return
- *   True if successful, FALSE otherwise
+ *   True if successful, FALSE otherwise.
  *
  * @ingroup tripal_mviews_api
  */
@@ -355,14 +359,14 @@ function tripal_populate_mview($mview_id) {
   $results = db_query($sql, array(':mview_id' => $mview_id));
   $mview = $results->fetchObject();
   if ($mview) {
-    // execute the query inside a transaction so that it doesn't destroy existing data
-    // that may leave parts of the site unfunctional
+    // Execute the query inside a transaction so that it doesn't destroy 
+    // existing data that may leave parts of the site unfunctional.
     $transaction = db_transaction();
     $previous_db = chado_set_active('chado');  // use chado database
     try {
       $success = chado_query("DELETE FROM {" . $mview->mv_table . "}");
       $success = chado_query("INSERT INTO {" . $mview->mv_table . "} ($mview->query)");
-      // if success get the number of results and update the table record
+      // If success get the number of results and update the table record.
       if ($success) {
         $sql = "SELECT count(*) as cnt FROM {" . $mview->mv_table . "}";
         $results = chado_query($sql);
@@ -373,7 +377,7 @@ function tripal_populate_mview($mview_id) {
         $record->status = "Populated with " . number_format($count->cnt) . " rows";
         drupal_write_record('tripal_mviews', $record, 'mview_id');
       }
-      // if not success then throw an error
+      // If not success then throw an error.
       else {
         throw new Exception("ERROR populating the materialized view ". $mview->mv_table . ". See Drupal's recent log entries for details.");
       }
@@ -382,7 +386,7 @@ function tripal_populate_mview($mview_id) {
     catch (Exception $e) {
       $transaction->rollback();
       chado_set_active($previous_db);
-      // print and save the error message
+      // Print and save the error message.
       $record = new stdClass();
       $record->mview_id = $mview_id;
       $record->status = "ERROR populating $mview->mv_table. See Drupal's recent log entries for details.\n";

tripal_chado/api/tripal_chado.property.api.inc

@@ -6,11 +6,11 @@
 
 /**
  * @defgroup tripal_chado_prop_api Chado Properties
- *
  * @ingroup tripal_api
+ * @{
  * The Chado Properties API provides a set of functions for interacting
  * with the any chado prop table.
- *
+ * @}
  */
 
 /**
@@ -39,8 +39,8 @@
  * @return
  *   An array in the same format as that generated by the function
  *   chado_generate_var().  If only one record is returned it
- *   is a single object.  If more than one record is returned then it is an array
- *   of objects
+ *   is a single object.  If more than one record is returned then it is an 
+ *   array of objects
  *
  * @ingroup tripal_chado_prop_api
  */
@@ -76,7 +76,7 @@ function chado_get_property($record, $property) {
     $type['cvterm_id'] = $type_id;
   }
 
-  // Make sure the CV term exists;
+  // Make sure the CV term exists.
   $options = array();
   $term = chado_select_record('cvterm', array('cvterm_id'), $type, $options);
   if (!$term or count($term) == 0) {
@@ -92,17 +92,17 @@ function chado_get_property($record, $property) {
         array('%property' => print_r($property, TRUE)));    return FALSE;
   }
 
-  // get the foreign key for this property table
+  // Get the foreign key for this property table.
   $table_desc = chado_get_schema($base_table . 'prop');
   $fkcol = key($table_desc['foreign keys'][$base_table]['columns']);
 
-  // construct the array of values to be selected
+  // Construct the array of values to be selected.
   $values = array(
     $fkcol => $base_id,
     'type_id' => $type,
   );
 
-  // if we have the unique property_id make sure to add that to the values
+  // If we have the unique property_id make sure to add that to the values.
   if ($prop_id) {
     $property_pkey = $table_desc['primary key'][0];
     $values[$property_pkey] = $prop_id;
@@ -127,7 +127,7 @@ function chado_get_property($record, $property) {
  *   should be assigned.  The following keys must be used:
  *     -table: The base table for which the property should be inserted.
  *         Thus to insert a property for a feature the base_table=feature and
- *         property is inserted into featureprop
+ *         property is inserted into featureprop.
  *     -id: The primary key value of the base table. The property will be
  *         associated with the record that matches this id.
  * @param $property
@@ -154,7 +154,7 @@ function chado_get_property($record, $property) {
  *        'force_rank' is set then an error will occur.
  *
  * @return
- *   Return TRUE if successful and FALSE otherwise
+ *   Return TRUE if successful and FALSE otherwise.
  *
  * @ingroup tripal_chado_prop_api
  */
@@ -191,9 +191,9 @@ function chado_insert_property($record, $property, $options = array()) {
     }
     else {
       if (!$force_rank) {
-        // iterate through the properties returned and check to see if the
+        // Iterate through the properties returned and check to see if the
         // property with this value already exists if not, get the largest rank
-        // and insert the same property but with this new value
+        // and insert the same property but with this new value.
         foreach ($props as $prop) {
           if ($prop->rank > $rank) {
             $rank = $prop->rank;
@@ -202,7 +202,7 @@ function chado_insert_property($record, $property, $options = array()) {
             return TRUE;
           }
         }
-        // now add 1 to the rank
+        // Now add 1 to the rank.
         $rank++;
       }
       else {
@@ -234,7 +234,7 @@ function chado_insert_property($record, $property, $options = array()) {
     $values['cvterm_id'] = $type_id;
   }
 
-  // Make sure the CV term exists;
+  // Make sure the CV term exists.
   $options = array();
   $term = chado_select_record('cvterm', array('cvterm_id'), $values, $options);
   if (!$term or count($term) == 0) {
@@ -251,7 +251,7 @@ function chado_insert_property($record, $property, $options = array()) {
   }
 
 
-    //Check that the cvalue property exists
+    // Check that the cvalue property exists.
     if ($cvalue_id){
         $term = chado_select_record('cvterm', array('cvterm_id'), array('cvterm_id' => $cvalue_id), $options);
        if (!$term or count($term) == 0) {
@@ -264,7 +264,7 @@ function chado_insert_property($record, $property, $options = array()) {
   }
 
 
-  // Get the foreign key for this property table
+  // Get the foreign key for this property table.
   $table_desc = chado_get_schema($base_table . 'prop');
   $fkcol = key($table_desc['foreign keys'][$base_table]['columns']);
 
@@ -303,7 +303,8 @@ function chado_insert_property($record, $property, $options = array()) {
  *     -value: The specific value for the property.
  *     -rank: The specific rank for the property.
  *     -cvalue_id: The cvterm_id of the value for the property.
- *      **note** cvalue_id is an anticipated column in the the next Chado release (1.4).  It is included here for early adopters.
+ *      **note** cvalue_id is an anticipated column in the the next Chado 
+ *      release (1.4).  It is included here for early adopters.
  *
  * @param $options
  *   An associative array containing the following keys:
@@ -312,7 +313,7 @@ function chado_insert_property($record, $property, $options = array()) {
  *
  *
  * @return
- *   Return TRUE on Update/Insert and FALSE otherwise
+ *   Return TRUE on Update/Insert and FALSE otherwise.
  *
  * @ingroup tripal_chado_prop_api
  */
@@ -332,7 +333,7 @@ function chado_update_property($record, $property, $options = array()) {
 
   $insert_if_missing = array_key_exists('insert_if_missing', $options) ? $options['insert_if_missing'] : FALSE;
 
-  // first see if the property is missing (we can't update a missing property
+  // First see if the property is missing (we can't update a missing property.
   $prop = chado_get_property($record, $property);
   if (count($prop) == 0) {
     if ($insert_if_missing) {
@@ -360,7 +361,7 @@ function chado_update_property($record, $property, $options = array()) {
     $type['cvterm_id'] = $type_id;
   }
 
-  // Make sure the CV term exists;
+  // Make sure the CV term exists.
   $options = array();
   $term = chado_select_record('cvterm', array('cvterm_id'), $type, $options);
   if (!$term or count($term) == 0) {
@@ -378,11 +379,11 @@ function chado_update_property($record, $property, $options = array()) {
   }
 
 
-  // Get the foreign key for this property table
+  // Get the foreign key for this property table.
   $table_desc = chado_get_schema($base_table . 'prop');
   $fkcol = key($table_desc['foreign keys'][$base_table]['columns']);
 
-  // construct the array that will match the exact record to update
+  // Construct the array that will match the exact record to update.
   $match = array(
     $fkcol => $base_id,
     'type_id' => $type,
@@ -404,7 +405,7 @@ function chado_update_property($record, $property, $options = array()) {
     $values['rank'] = $rank;
   }
 
-  // If a cvalue_id is supplied, check that it is a valid cvterm
+  // If a cvalue_id is supplied, check that it is a valid cvterm.
     if ($cvalue_id) {
         $term = chado_select_record('cvterm', array('cvterm_id'), array('cvterm_id' => $cvalue_id), $options);
         if (!$term or count($term) == 0) {
@@ -417,7 +418,7 @@ function chado_update_property($record, $property, $options = array()) {
   }
 
   // If we have the unique property_id then we can also update the type
-  // thus add it to the values to be updated
+  // thus add it to the values to be updated.
   if ($prop_id) {
     $values['type_id'] = $type;
   }
@@ -426,7 +427,7 @@ function chado_update_property($record, $property, $options = array()) {
 }
 
 /**
- * Deletes a property for a given base table record using the property name
+ * Deletes a property for a given base table record using the property name.
  *
  * @param $record
  *   An associative array used to identify the record to which the property
@@ -450,7 +451,7 @@ function chado_update_property($record, $property, $options = array()) {
  *     -rank: The specific rank for the property.
  *
  * @return
- *   Return TRUE on successful deletion and FALSE otherwise
+ *   Return TRUE on successful deletion and FALSE otherwise.
  *
  * @ingroup tripal_chado_prop_api
  */
@@ -468,7 +469,7 @@ function chado_delete_property($record, $property) {
   $rank        = array_key_exists('rank', $property) ? $property['rank'] : 0;
 
 
-  // Build the values array for checking if the CVterm exists
+  // Build the values array for checking if the CVterm exists.
   $type = array();
   if ($cv_id) {
     $type['cv_id'] = $cv_id;
@@ -485,7 +486,7 @@ function chado_delete_property($record, $property) {
     $type['cvterm_id'] = $type_id;
   }
 
-  // Make sure the CV term exists;
+  // Make sure the CV term exists.
   $options = array();
   $term = chado_select_record('cvterm', array('cvterm_id'), $type, $options);
   if (!$term or count($term) == 0) {
@@ -501,19 +502,20 @@ function chado_delete_property($record, $property) {
         array('%property' => print_r($property, TRUE)));    return FALSE;
   }
 
-  // get the foreign key for this property table
+  // Get the foreign key for this property table.
   $table_desc = chado_get_schema($base_table . 'prop');
   $fkcol = key($table_desc['foreign keys'][$base_table]['columns']);
 
-  // If we have the unique property_id, make sure to use it in the match to ensure
-  // we get the exact record. Doesn't rely on there only being one property of that type
+  // If we have the unique property_id, make sure to use it in the match to 
+  // ensure we get the exact record. Doesn't rely on there only being one 
+  // property of that type.
   if ($prop_id) {
     $property_pkey = $table_desc['primary key'][0];
     $match = array(
       $property_pkey => $prop_id
     );
   }
-  // construct the array that will match the exact record to update
+  // Construct the array that will match the exact record to update.
   else {
     $match = array(
       $fkcol => $record_id,
@@ -548,14 +550,15 @@ function chado_delete_property($record, $property) {
  *     -value: The specific value for the property.
  *     -rank: The specific rank for the property.
  *     -cvalue_id: The cvterm_id of the value for the property.
- *      **note** cvalue_id is an anticipated column in the the next Chado release (1.4).  It is included here for early adopters.
+ *      **note** cvalue_id is an anticipated column in the the next Chado 
+ *      release (1.4).  It is included here for early adopters.
  * 
  * @param $options
  *   An array of options supported by chado_generate_var(). These keys
  *   are used for generating the cvterm objects returned by this function.
  *
  * @return
- *   An array of chado variables with the given property
+ *   An array of chado variables with the given property.
  *
  * @ingroup tripal_chado_prop_api
  */
@@ -622,10 +625,11 @@ function chado_get_record_with_property($record, $property, $options = array())
     $values[$foreignkey_name] = $base_records;
   }
 
-  // Now select the ids of the base table that have the properties we want that match.
+  // Now select the ids of the base table that have the properties we want that 
+  // match.
   $select = chado_select_record($property_table, array($foreignkey_name), $values);
 
-  // For each of these ids, pull out the full base records
+  // For each of these ids, pull out the full base records.
   $records = array();
   foreach ($select as $s) {
     $id = $s->{$foreignkey_name};
@@ -643,8 +647,10 @@ function chado_get_record_with_property($record, $property, $options = array())
  * @param $prop_table
  *   The name of the property table.
  * @throws Exception
+ * 
  * @return
  *   An array of cvterm objects as created by chado_generate_var().
+ * 
  * @ingroup tripal_chado_prop_api
  */
 function chado_get_table_property_types($prop_table) {
@@ -660,4 +666,4 @@ function chado_get_table_property_types($prop_table) {
     $types[] = chado_generate_var('cvterm', array('cvterm_id' => $result->type_id));
   }
   return $types;
-}
+}

tripal_chado/api/tripal_chado.schema.api.inc

@@ -1,5 +1,12 @@
 <?php
 
+/**
+ * @file
+ * Provides an application programming interface (API) for describing Chado tables.
+ *
+ * @ingroup tripal_chado
+ */
+
 /**
  * @defgroup tripal_chado_schema_api Chado Schema
  * @ingroup tripal_chado_api

tripal_chado/api/tripal_chado.semweb.api.inc

@@ -1,4 +1,19 @@
 <?php
+
+/**
+ * @file
+ * Provides an application programming interface (API) for semantic web support.
+ *
+ * @ingroup tripal_chado
+ */
+/**
+ * @defgroup tripal_chado_semweb_api Semantic Web
+ * @ingroup tripal_chado_api
+ * @{
+ * Provides an application programming interface (API) for semantic web support.
+ * @}
+ */
+
 /**
  * Adds a new Chado table to the semantic web support for Chado.
  *
@@ -17,10 +32,12 @@
  *
  * @param $chado_table
  *   The name of the Chado table.
+ * 
+ * @ingroup tripal_chado_semweb_api
  */
 function tripal_add_chado_semweb_table($chado_table) {
 
-  // Don't include the tripal temp tables
+  // Don't include the tripal temp tables.
   if (preg_match('/tripal_.+_temp/', $chado_table)) {
     return;
   }
@@ -30,7 +47,7 @@ function tripal_add_chado_semweb_table($chado_table) {
   $schema = chado_get_schema($chado_table);
   foreach ($schema['fields'] as $chado_column => $details) {
 
-    // If the record already exists don't overwrite it
+    // If the record already exists don't overwrite it.
     $record = db_select('chado_semweb', 'CS')
       ->fields('CS', array('chado_semweb_id'))
       ->condition('CS.chado_table', $chado_table)
@@ -46,6 +63,7 @@ function tripal_add_chado_semweb_table($chado_table) {
     }
   }
 }
+
 /**
  * Associates a controlled vocabulary term with a field in a Chado table.
  *
@@ -71,6 +89,8 @@ function tripal_add_chado_semweb_table($chado_table) {
  *
  * @return boolean
  *   Returns TRUE if the association was made successfully and FALSE otherwise.
+ * 
+ *  @ingroup tripal_chado_semweb_api
  */
 function tripal_associate_chado_semweb_term($chado_table, $chado_column, $term,
     $update = FALSE) {
@@ -174,6 +194,8 @@ function tripal_associate_chado_semweb_term($chado_table, $chado_column, $term,
  *   Returns a string-based representation of the term (e.g. SO:0000704). If
  *   the 'return_object' options is provided then a cvterm object is returned.
  *   returns NULL if no term is mapped to the table and column.
+ * 
+ *  @ingroup tripal_chado_semweb_api
  */
 function tripal_get_chado_semweb_term($chado_table, $chado_column, $options = array()) {
   $cvterm_id = db_select('chado_semweb', 'CS')
@@ -200,6 +222,8 @@ function tripal_get_chado_semweb_term($chado_table, $chado_column, $options = ar
  *   A cvterm object.
  * @return
  *   The semantic web name for the term.
+ * 
+ *  @ingroup tripal_chado_semweb_api
  */
 function tripal_format_chado_semweb_term($cvterm) {
   if ($cvterm) {
@@ -219,6 +243,8 @@ function tripal_format_chado_semweb_term($cvterm) {
  * @return
  *   The name of the Chado column that matches the given term or FALSE if the
  *   term is not mapped to the Chado table.
+ * 
+ *  @ingroup tripal_chado_semweb_api
  */
 function tripal_get_chado_semweb_column($chado_table, $term) {
   $columns = db_select('chado_semweb', 'CS')

tripal_chado/api/tripal_chado.variables.api.inc

@@ -1,7 +1,18 @@
 <?php
+
 /**
  * @file
  * This API generates objects containing the full details of a record(s) in chado.
+ *
+ * @ingroup tripal_chado
+ */
+/**
+ * @defgroup tripal_chado_variables_api Semantic Web
+ * @ingroup tripal_chado_api
+ * 
+ * @{
+ * This API generates objects containing the full details of a record(s) in chado.
+ * @}
  */
 
 /**
@@ -130,7 +141,7 @@
  *   base table). If the option 'return_array' is provided the function
  *   always returns an array.
  *
- * @ingroup tripal_chado_query_api
+ * @ingroup tripal_chado_variables_api
  */
 function chado_generate_var($table, $values, $base_options = array()) {
   $all = new stdClass();
@@ -147,7 +158,7 @@ function chado_generate_var($table, $values, $base_options = array()) {
   if (array_key_exists('pager', $base_options)) {
     $pager = $base_options['pager'];
   }
-  // get description for the current table----------------------------------------------------------
+  // get description for the current table-------------------------------------
   $table_desc = chado_get_schema($table);
   if (!$table_desc or count($table_desc) == 0) {
     tripal_report_error('tripal_chado', TRIPAL_ERROR,
@@ -163,7 +174,7 @@ function chado_generate_var($table, $values, $base_options = array()) {
   $table_primary_key = $table_desc['primary key'][0];
   $table_columns = array_keys($table_desc['fields']);
 
-  // Expandable fields without value needed for criteria--------------------------------------------
+  // Expandable fields without value needed for criteria-----------------------
   // Add in the default expandable arrays
   // These are used for later expanding fields, tables, foreign keys and nodes
   $all->expandable_fields = array();
@@ -183,34 +194,36 @@ function chado_generate_var($table, $values, $base_options = array()) {
 
   // This allows modules to specify that some fields should be excluded by default
   // For example, tripal core provides a tripal_chado_exclude_field_from_feature_by_default()
-  // which says that we usually don't want to include the residues field by default since
-  // it can be very large and cause performance issues.
+  // which says that we usually don't want to include the residues field by 
+  // default since it can be very large and cause performance issues.
 
-  // If a field is excluded by default it can always be expanded at a later point by calling
-  // chado_expand_var($chado_var, 'field', <field name as shown in expandable_fields array>);
+  // If a field is excluded by default it can always be expanded at a later 
+  // point by calling chado_expand_var($chado_var, 'field', 
+  // <field name as shown in expandable_fields array>);
 
   // First get an array of all the fields to be removed for the current table
-  // module_invoke_all() is drupal's way of invoking all implementations of the specified
-  // hook and merging all of the results.
+  // module_invoke_all() is drupal's way of invoking all implementations of the 
+  // specified hook and merging all of the results.
 
   // $fields_to_remove should be an array with the keys matching field names
-  // and the values being strings to be executed using php_eval() to determine whether
-  // to exclude the field (evaluates to TRUE) or not (evaluates to FALSE)
+  // and the values being strings to be executed using php_eval() to determine 
+  // whether to exclude the field (evaluates to TRUE) or not (evaluates to FALSE)
   $fields_to_remove = module_invoke_all('exclude_field_from_' . $table . '_by_default');
 
   // Now, for each field to be removed
   foreach ($fields_to_remove as $field_name => $criteria) {
 
-    //replace <field_name> with the current field name
+    //Replace <field_name> with the current field name
     $field_name_safe = preg_replace("/\'\"\\\/", '\\1', $field_name);
     $criteria = preg_replace('/<field_name> /', $field_name_safe, $criteria);
-    // if field_value needed we can't deal with this field yet
+    // If field_value needed we can't deal with this field yet.
     if (preg_match('/<field_value> /', $criteria)) {
       break;
     }
 
-    //if criteria then remove from query
-    // @coder-ignore: only module designers can populate $criteria -not a security risk
+    // If criteria then remove from query
+    // @coder-ignore: only module designers can populate $criteria -not a 
+    // security risk.
     $success = php_eval('<?php return ' . $criteria . '; ?>');
     if ($success) {
       unset($table_columns[array_search($field_name, $table_columns)]);
@@ -222,40 +235,43 @@ function chado_generate_var($table, $values, $base_options = array()) {
   // Get fields to be removed by type................................
   // This gets all implementations of hook_exclude_type_by_default().
 
-  // This allows modules to specify that some types of fields should be excluded by default
-  // For example, tripal core provides a tripal_chado_exclude_type_by_default() which says
-  // that text fields are often very large and if they are longer than 250 characters then
+  // This allows modules to specify that some types of fields should be excluded 
+  // by default For example, tripal core provides a 
+  // tripal_chado_exclude_type_by_default() which says that text fields are 
+  // often very large and if they are longer than 250 characters then
   // we want to exclude them by default
 
-  // If a field is excluded by default it can always be expanded at a later point by calling
-  // chado_expand_var($chado_var, 'field', <field name as shown in expandable_fields array>);
+  // If a field is excluded by default it can always be expanded at a later 
+  // point by calling chado_expand_var($chado_var, 'field', 
+  //<field name as shown in expandable_fields array>);
 
-  // First get an array of all the types of fields to be removed for the current table
-  // module_invoke_all() is drupal's way of invoking all implementations of the specified
-  // hook and merging all of the results.
+  // First get an array of all the types of fields to be removed for the current
+  // table module_invoke_all() is drupal's way of invoking all implementations 
+  // of the specified hook and merging all of the results.
 
   // $types_to_remove should be an array with the keys matching field names
-  // and the values being strings to be executed using php_eval() to determine whether
-  // to exclude the field (evaluates to TRUE) or not (evaluates to FALSE)
+  // and the values being strings to be executed using php_eval() to determine 
+  // whether to exclude the field (evaluates to TRUE) or not (evaluates to FALSE)
   // (ie: array('text' => 'strlen("<field_value> ") > 100');
   $types_to_remove = module_invoke_all('exclude_type_by_default');
 
   // Get a list of all the types of fields
-  // the key is the type of field and the value is an array of fields of this type
+  // the key is the type of field and the value is an array of fields of this 
+  // type.
   $field_types = array();
   foreach ($table_desc['fields'] as $field_name => $field_array) {
     $field_types[$field_array['type']][] = $field_name;
   }
 
-  // We want to use the types to remove in conjunction with our table field descriptions
-  // to determine which fields might need to be removed
+  // We want to use the types to remove in conjunction with our table field 
+  // descriptions to determine which fields might need to be removed.
   foreach ($types_to_remove as $field_type => $criteria) {
 
-    // if there are fields of that type to remove
+    // If there are fields of that type to remove.
     if (isset($field_types[$field_type])) {
 
       // Do any processing needed on the php criteria
-      //replace <field_name>  with the current field name
+      //replace <field_name>  with the current field name.
       $field_name_safe = preg_replace('/\'|"|\\\/', '\\1', $field_name);
       $criteria = preg_replace('/<field_name> /', $field_name_safe, $criteria);
       foreach ($field_types[$field_type] as $field_name) {
@@ -265,19 +281,20 @@ function chado_generate_var($table, $values, $base_options = array()) {
           continue;
         }
 
-        // if criteria then remove from query
-        // (as long as <field_value> is not needed for the criteria to be evaluated)
-        // @coder-ignore: only module designers can populate $criteria -not a security risk
+        // If criteria then remove from query
+        // (as long as <field_value> is not needed for the criteria to be 
+        // evaluated) @coder-ignore: only module designers can populate 
+        //$criteria -not a security risk.
         $success = php_eval('<?php return ' . $criteria . '; ?>');
         if ($success) {
           unset($table_columns[array_search($field_name, $table_columns)]);
           $all->expandable_fields[] = $table . '.' . $field_name;
         }
-      } //end of foreach field of that type
+      } // End of foreach field of that type.
     }
-  } //end of foreach type to be removed
+  } // End of foreach type to be removed.
 
-  // get the values for the record in the current table---------------------------------------------
+  // Get the values for the record in the current table-------------------------
   $results = chado_select_record($table, $table_columns, $values, $base_options);
 
   if ($results) {
@@ -285,7 +302,7 @@ function chado_generate_var($table, $values, $base_options = array()) {
     // Iterate through each result.
     foreach ($results as $key => $object) {
 
-      // Add empty expandable_x arrays
+      // Add empty expandable_x arrays.
       $object->expandable_fields = $all->expandable_fields;
       $object->expandable_foreign_keys = $all->expandable_foreign_keys;
       $object->expandable_tables = $all->expandable_tables;
@@ -294,11 +311,12 @@ function chado_generate_var($table, $values, $base_options = array()) {
       $object->tablename = $table;
 
       // For Tripal v2 compatibility
-      // check if the current table maps to a node type-----------------------------------------------
-      // if this table is connected to a node there will be a chado_tablename table in drupal
+      // check if the current table maps to a node type-------------------------
+      // If this table is connected to a node there will be a chado_tablename 
+      // table in drupal.
       if (module_exists('tripal_core') and db_table_exists('chado_' . $table)) {
-        // that has a foreign key to this one ($table_desc['primary key'][0]
-        // and to the node table (nid)
+        // That has a foreign key to this one ($table_desc['primary key'][0]
+        // and to the node table (nid).
         $sql = "
           SELECT $table_primary_key, nid
           FROM {chado_$table}
@@ -319,13 +337,14 @@ function chado_generate_var($table, $values, $base_options = array()) {
         $object->entity_id = $entity_id;
       }
 
-      // remove any fields where criteria needs to be evalulated---------------------------------------
+      // Remove any fields where criteria needs to be evalulated----------------
       // The fields to be removed can be populated by implementing either
-      // hook_exclude_field_from_<table>_by_default() where <table> is the current table
-      // OR hook_exclude_type_by_default() where there are fields of the specified type in the current table
-      // It only reaches this point if the criteria specified for whether or not to
-      // exclude the field includes <field_value> which means it has to be evaluated after
-      // the query has been executed
+      // hook_exclude_field_from_<table>_by_default() where <table> is the 
+      // current table OR hook_exclude_type_by_default() where there are fields 
+      // of the specified type in the current table It only reaches this point 
+      // if the criteria specified for whether or not to exclude the field 
+      // includes <field_value> which means it has to be evaluated after
+      // the query has been executed.
       foreach ($fields_to_remove as $field_name => $criteria) {
 
         // If the field is an object then we don't support exclusion of it
@@ -334,7 +353,8 @@ function chado_generate_var($table, $values, $base_options = array()) {
           break;
         }
 
-        // replace <field_value> with the actual value of the field from the query
+        // Replace <field_value> with the actual value of the field from the 
+        // query.
         $field_name_safe = preg_replace('/\'|"|\\\/', '\\1', $object->{$field_name});
         $criteria = preg_replace('/<field_value>/', $field_name_safe, $criteria);
 
@@ -348,34 +368,35 @@ function chado_generate_var($table, $values, $base_options = array()) {
         }
       }
 
-      // recursively follow foreign key relationships nesting objects as we go------------------------
+      // Recursively follow foreign key relationships nesting objects as we go------------------------
       if (array_key_exists('foreign keys', $table_desc) and $table_desc['foreign keys']) {
         foreach ($table_desc['foreign keys'] as $foreign_key_array) {
           $foreign_table = $foreign_key_array['table'];
           foreach ($foreign_key_array['columns'] as $foreign_key => $primary_key) {
 
-            // Note: Foreign key is the field in the current table whereas primary_key is the field in
-            // the table referenced by the foreign key
-            //Dont do anything if the foreign key is empty
+            // Note: Foreign key is the field in the current table whereas 
+            // primary_key is the field in the table referenced by the foreign 
+            // key, don't do anything if the foreign key is empty
             if (empty($object->{$foreign_key})) {
               continue;
             }
 
             if (is_array($include_fk)) {
-              // don't recurse if the callee has supplied an $fk_include list and this
-              // FK table is not in the list.
+              // Don't recurse if the callee has supplied an $fk_include list 
+              // and this FK table is not in the list.
               if (is_array($include_fk) and !array_key_exists($foreign_key, $include_fk)) {
                 $object->expandable_foreign_keys[] = $table . '.' . $foreign_key . ' => ' . $foreign_table;
                 continue;
               }
             }
-            // if we have the option but it is not an array then we don't recurse any furutehr
+            // If we have the option but it is not an array then we don't 
+            // recurse any further.
             if ($include_fk === TRUE) {
               $object->expandable_foreign_keys[] = $table . '.' . $foreign_key . ' => ' . $foreign_table;
               continue;
             }
 
-            // get the record from the foreign table
+            // Get the record from the foreign table.
             $foreign_values = array($primary_key => $object->{$foreign_key});
             $options = array();
             if (is_array($include_fk)) {
@@ -384,9 +405,9 @@ function chado_generate_var($table, $values, $base_options = array()) {
 
             $foreign_object = chado_generate_var($foreign_table, $foreign_values, $options);
 
-            // add the foreign record to the current object in a nested manner
+            // Add the foreign record to the current object in a nested manner.
             $object->{$foreign_key} = $foreign_object;
-            // Flatten expandable_x arrays so only in the bottom object
+            // Flatten expandable_x arrays so only in the bottom object.
             if (property_exists($object->{$foreign_key}, 'expandable_fields') and
                 is_array($object->{$foreign_key}->expandable_fields)) {
               $object->expandable_fields = array_merge(
@@ -426,26 +447,26 @@ function chado_generate_var($table, $values, $base_options = array()) {
     }
   }
 
-  // convert the results into an array
+  // Convert the results into an array.
   $results_arr = array();
   foreach ($results as $record) {
     $results_arr[] = $record;
   }
-  // check only one result returned
+  // Check only one result returned.
   if (!$return_array) {
     if (sizeof($results_arr) == 1) {
-      // add results to object
+      // Add results to object.
       return $results_arr[0];
     }
     elseif (!empty($results_arr)) {
       return $results_arr;
     }
     else {
-      // no results returned
+      // No results returned.
     }
   }
-  // the caller has requested results are always returned as
-  // an array
+  // The caller has requested results are always returned as
+  // an array.
   else {
     if (!$results_arr) {
       return array();
@@ -550,16 +571,16 @@ function chado_generate_var($table, $values, $base_options = array()) {
  *   - return_array:
  *     Additionally,  The option 'return_array' can be provided to force
  *     the function to expand tables as an array. Default behavior is to expand
- *     a table as single record if only one record exists or to expand as an array if
- *     multiple records exist.
+ *     a table as single record if only one record exists or to expand as an 
+ *     array if multiple records exist.
  *   - include_fk:
  *     an array of FK relationships to follow. By default, the
  *     chado_expand_var function will follow all FK relationships but this
- *     may generate more queries then is desired slowing down this function call when
- *     there are lots of FK relationships to follow.  Provide an array specifying the
- *     fields to include.  For example, if expanding a property table (e.g. featureprop)
- *     and you want the CV and accession but do not want the DB the following
- *     array would work:
+ *     may generate more queries then is desired slowing down this function call
+ *     when there are lots of FK relationships to follow.  Provide an array 
+ *     specifying the fields to include.  For example, if expanding a property 
+ *     table (e.g. featureprop) and you want the CV and accession but do not 
+ *     want the DB the following array would work:
  *        $table_options =  array(
  *          'include_fk' => array(
  *            'type_id' => array(
@@ -583,21 +604,22 @@ function chado_generate_var($table, $values, $base_options = array()) {
  *     This options is only used where type=table and allows you to
  *     expand only a subset of results based on the given criteria. Criteria
  *     should provided as an array of [field name] => [value] similar to the
- *     values array provided to chado_generate_var(). For example, when expanding
- *     the featureprop table for a feature, you will already get only properties
- *     for that feature, this option allows you to further get only properties
- *     of a given type by passing in array('type_id' => array('name' => [name of type]))
+ *     values array provided to chado_generate_var(). For example, when 
+ *     expanding the featureprop table for a feature, you will already get only 
+ *     properties for that feature, this option allows you to further get only 
+ *     properties of a given type by passing in 
+ *     array('type_id' => array('name' => [name of type]))
  * @return
- *   A chado object supplemented with the field/table/node requested to be expanded.
- *   If the type is a table and it has already been expanded no changes is made to the
- *   returned object
+ *   A chado object supplemented with the field/table/node requested to be 
+ *   expanded. If the type is a table and it has already been expanded no 
+ *   changes is made to the returned object
  *
  *
- * @ingroup tripal_chado_query_api
+ * @ingroup tripal_chado_variables_api
  */
 function chado_expand_var($object, $type, $to_expand, $table_options = array()) {
 
-  // make sure we have a value
+  // Make sure we have a value.
   if (!$object) {
     tripal_report_error('tripal_chado',
       TRIPAL_ERROR,
@@ -606,7 +628,7 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
     return $object;
   }
 
-  // check to see if we are expanding an array of objects
+  // Check to see if we are expanding an array of objects.
   if (is_array($object)) {
     foreach ($object as $index => $o) {
       $object[$index] = chado_expand_var($o, $type, $to_expand);
@@ -614,20 +636,20 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
     return $object;
   }
 
-  // get the base table name
+  // Get the base table name.
   $base_table = $object->tablename;
 
   switch ($type) {
-    case "field": //--------------------------------------------------------------------------------
+    case "field": //------------------------------------------------------------
       if (preg_match('/(\w+)\.(\w+)/', $to_expand, $matches)) {
         $tablename = $matches[1];
         $fieldname = $matches[2];
         $table_desc = chado_get_schema($tablename);
 
-        // BASE CASE: the field is from the current table
+        // BASE CASE: the field is from the current table.
         if ($base_table == $tablename) {
           // Use the table description to fully describe the current object
-          // in a $values array to be used to select the field from chado
+          // in a $values array to be used to select the field from chado.
           $values = array();
           foreach ($table_desc['primary key'] as $key) {
             if(property_exists($object, $key)) {
@@ -635,21 +657,21 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
             }
           }
 
-          // Retrieve the field from Chado
+          // Retrieve the field from Chado.
           $results = chado_select_record($tablename, array($fieldname), $values);
 
-          // Check that the field was retrieved correctly
+          // Check that the field was retrieved correctly.
           if (isset($results[0])) {
             $object->{$fieldname} = $results[0]->{$fieldname};
             $object->expanded = $to_expand;
           }
-          // If it wasn't retrieved correctly, we need to warn the administrator
+          // If it wasn't retrieved correctly, we need to warn the administrator.
 
         }
-        // RECURSIVE CASE: the field is in a nested object
+        // RECURSIVE CASE: the field is in a nested object.
         else {
           // We want to look at each field and if it's an object then we want to
-          // attempt to expand the field in it via recursion
+          // attempt to expand the field in it via recursion.
           foreach ((array) $object as $field_name => $field_value) {
             if (is_object($field_value)) {
               $object->{$field_name} = chado_expand_var(
@@ -658,11 +680,11 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
               $to_expand
               );
             }
-          } //end of for each field in the current object
+          } // End of for each field in the current object.
         }
       }
       // Otherwise we weren't able to extract the parts of the field to expand
-      // Thus we will warn the administrator
+      // Thus we will warn the administrator.
       else {
         tripal_report_error('tripal_chado', TRIPAL_ERROR,
           'chado_expand_var: Field (%field) not in the right format. " .
@@ -670,21 +692,22 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
       }
       break;
 
-    case "foreign_key": //--------------------------------------------------------------------------
+    case "foreign_key": //-----------------------------------------------------
       if (preg_match('/(\w+)\.(\w+) => (\w+)/', $to_expand, $matches)) {
         $table_name = $matches[1];
         $field_name = $matches[2];
         $foreign_table = $matches[3];
         $table_desc = chado_get_schema($table_name);
 
-        // BASE CASE: The foreign key is from the current table
+        // BASE CASE: The foreign key is from the current table.
         if ($base_table == $table_name) {
 
           // Get the value of the foreign key from the object
           $field_value = $object->{$field_name};
 
-          // Get the name of the field in the foreign table using the table description
-          // For example, with the feature.type_id => cvterm.cvterm_id we need cvterm_id
+          // Get the name of the field in the foreign table using the table 
+          // description For example, with the 
+          // feature.type_id => cvterm.cvterm_id we need cvterm_id
           $foreign_field_name = FALSE;
           foreach ($table_desc['foreign keys'][$foreign_table]['columns'] as $left => $right) {
             if ($right == $field_name) {
@@ -692,23 +715,25 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
             }
           }
 
-          // Check that we were able to determine the field name in the foreign table
+          // Check that we were able to determine the field name in the foreign
+          // table.
           if ($foreign_field_name) {
 
             // Generate a chado variable of the foreign key
             // For example, if the foreign key to expand is feature.type_id
-            // then we want to generate a chado cvterm variable that matches the feature.type_id
+            // then we want to generate a chado cvterm variable that matches the 
+            // feature.type_id.
             $foreign_var = chado_generate_var(
               $foreign_table, // thus in the example above, generate a cvterm var
               array($foreign_field_name => $field_value), // where the cvterm.cvterm_id = feature.type_id value
               $table_options //pass in the same options given to this function
             );
 
-            // Check that the foreign object was returned
+            // Check that the foreign object was returned.
             if ($foreign_var) {
 
-              // It was so now we can add this chado variable to our current object
-              // in place of the key value
+              // It was so now we can add this chado variable to our current 
+              // object in place of the key value.
               $object->{$field_name} = $foreign_var;
               $object->expanded = $to_expand;
 
@@ -721,7 +746,7 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
                 array('%fk' => $to_expand));
             }
           }
-          // Else we were unable to determine the field name in the foreign table
+          // Else we were unable to determine the field name in the foreign table.
           else {
             tripal_report_error('tripal_chado', TRIPAL_ERROR,
               'chado_expand_var: unable to determine the field name in the table the foreign
@@ -730,7 +755,7 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
           }
 
         }
-        // RECURSIVE CASE: Check any nested objects
+        // RECURSIVE CASE: Check any nested objects.
         else {
 
           foreach ((array) $object as $field_name => $field_value) {
@@ -741,12 +766,12 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
               $to_expand
               );
             }
-          } //end of for each field in the current object
+          } //End of for each field in the current object.
 
         }
       }
-      // Otherwise we weren't able to extract the parts of the foreign key to expand
-      // Thus we will warn the administrator
+      // Otherwise we weren't able to extract the parts of the foreign key to 
+      // expand thus we will warn the administrator.
       else {
         tripal_report_error('tripal_chado', TRIPAL_ERROR,
           'chado_expand_var: foreign_key (%fk) not in the right format. " .
@@ -754,7 +779,7 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
       }
       break;
 
-    case "table": //--------------------------------------------------------------------------------
+    case "table": //------------------------------------------------------------
       $foreign_table = $to_expand;
 
       // BASE CASE: don't expand the table it already is expanded
@@ -763,15 +788,16 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
       }
       $foreign_table_desc = chado_get_schema($foreign_table);
 
-      // TODO: if we don't get a foreign_table (which could happen of a custom table
-      // is not correctly defined or the table name is mispelled then we should return
-      // gracefully.
+      // TODO: if we don't get a foreign_table (which could happen of a custom 
+      // table is not correctly defined or the table name is mispelled then we 
+      // should return gracefully.
 
       // BASE CASE: If it's connected to the base table via a FK constraint
-      // then we have all the information needed to expand it now
+      // then we have all the information needed to expand it now.
       if (array_key_exists($base_table, $foreign_table_desc['foreign keys'])) {
         foreach ($foreign_table_desc['foreign keys'][$base_table]['columns'] as $left => $right) {
-          // if the FK value in the base table is not there then we can't expand it, so just skip it.
+          // if the FK value in the base table is not there then we can't expand
+          // it, so just skip it.
           if (!$object->{$right}) {
             continue;
           }
@@ -800,15 +826,17 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
             $filter_criteria = array($left => $object->{$right});
           }
 
-          // generate a new object for this table using the FK values in the base table.
+          // Generate a new object for this table using the FK values in the 
+          // base table.
           $new_options = $table_options;
           $foreign_object = chado_generate_var($foreign_table, $filter_criteria, $new_options);
 
-          // if the generation of the object was successful, update the base object to include it.
+          // If the generation of the object was successful, update the base 
+          // object to include it.
           if ($foreign_object) {
-            // in the case where the foreign key relationship exists more
-            // than once with the same table we want to alter the array structure to
-            // include the field name.
+            // In the case where the foreign key relationship exists more
+            // than once with the same table we want to alter the array 
+            // structure to include the field name.
             if (count($foreign_table_desc['foreign keys'][$base_table]['columns']) > 1) {
               if (!property_exists($object, $foreign_table)) {
                 $object->{$foreign_table} = new stdClass();
@@ -825,11 +853,11 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
               $object->expanded = $to_expand;
             }
           }
-          // if the object returned is NULL then handle that
+          // If the object returned is NULL then handle that.
           else {
-            // in the case where the foreign key relationship exists more
-            // than once with the same table we want to alter the array structure to
-            // include the field name.
+            // In the case where the foreign key relationship exists more
+            // than once with the same table we want to alter the array 
+            // structure to include the field name.
             if (count($foreign_table_desc['foreign keys'][$base_table]['columns']) > 1) {
               if (!property_exists($object, $foreign_table)) {
                 $object->{$foreign_table} = new stdClass();
@@ -842,30 +870,32 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
           }
         }
       }
-      // RECURSIVE CASE: if the table is not connected directly to the current base table
-      // through a foreign key relationship, then maybe it has a relationship to
-      // one of the nested objects.
+      // RECURSIVE CASE: if the table is not connected directly to the current 
+      // base table through a foreign key relationship, then maybe it has a 
+      // relationship to one of the nested objects.
       else {
 
-        // We need to recurse -the table has a relationship to one of the nested objects
-        // We assume it's a nested object if the value of the field is an object
+        // We need to recurse -the table has a relationship to one of the nested
+        // objects. We assume it's a nested object if the value of the field is 
+        // an object.
         $did_expansion = 0;
         foreach ((array) $object as $field_name => $field_value) {
 
-          // CASE #1: This field is an already expanded foreign key and the table to be
-          // expanded is in the table referenced by the foreign key
+          // CASE #1: This field is an already expanded foreign key and the 
+          // table to be expanded is in the table referenced by the foreign key.
 
           // First of all it can only be expanded if it's an object
-          // And if it's a foreign key it should have a tablename property
+          // And if it's a foreign key it should have a tablename property.
           if (is_object($field_value) AND property_exists($field_value, 'tablename')) {
             $object->{$field_name} = chado_expand_var($field_value, 'table', $foreign_table);
           }
 
-          // CASE #2: This field is an already expanded object (ie: the field is actually
-          // the expanded table name) and the table to be expanded si related to it
+          // CASE #2: This field is an already expanded object (ie: the field is
+          // actually the expanded table name) and the table to be expanded is 
+          // related to it.
 
-          // check to see if the $field_name is a valid chado table, we don't need
-          // to call chado_expand_var on fields that aren't tables
+          // Check to see if the $field_name is a valid chado table, we don't 
+          // need to call chado_expand_var on fields that aren't tables.
           $check = chado_get_schema($field_name);
           if ($check) {
             $did_expansion = 1;
@@ -873,8 +903,8 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
           }
         }
 
-        // if we did not expand this table we should return a message that the foreign table
-        // could not be expanded
+        // If we did not expand this table we should return a message that the 
+        // foreign tabl could not be expanded.
         if (!$did_expansion) {
           tripal_report_error('tripal_chado', TRIPAL_ERROR, 'chado_expand_var: Could not expand %table. ' .
             'The table is either not related to the base object through a foreign key relationships or ' .
@@ -886,19 +916,21 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
       }
       break;
 
-    case "node": //---------------------------------------------------------------------------------
+    case "node": //-------------------------------------------------------------
 
-      // BASE CASE: if the node to be expanded is for our base table, then just expand it
+      // BASE CASE: if the node to be expanded is for our base table, then just 
+      // expand it.
       if ($object->tablename == $to_expand) {
 
-        // Load the node based on the current objects nid (node primary key)
+        // Load the node based on the current objects nid (node primary key).
         $node = NULL;
         if (property_exists($object, 'nid')) {
           $node = node_load($object->nid);
         }
-        // Try to get the nid based on the tablename
+        // Try to get the nid based on the tablename.
         else {
-          // Invoke all hook_node_info to avoid hard-coding the chado_$table assumption
+          // Invoke all hook_node_info to avoid hard-coding the chado_$table 
+          // assumption..
           foreach (module_invoke_all('node_info') as $node_info) {
             if (array_key_exists('chado_node_api', $node_info)) {
               if ($node_info['chado_node_api']['base_table'] == $object->tablename) {
@@ -920,7 +952,7 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
         // If we have successfully loaded the node...
         if ($node) {
 
-          // Move expandable arrays from the object into the node
+          // Move expandable arrays from the object into the node.
           $object->expanded = $to_expand;
           $node->expandable_fields = $object->expandable_fields;
           unset($object->expandable_fields);
@@ -930,13 +962,14 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
           unset($object->expandable_nodes);
 
           // The node becomes the base object with the obejct added to it.
-          // For example, we may start with a feature object with a name, uniquename , type, etc.
-          // After expanding we will return the node and at $node->feature you will find the original object
+          // For example, we may start with a feature object with a name, 
+          // uniquename , type, etc. After expanding we will return the node and
+          // at $node->feature you will find the original object.
           $node->{$base_table} = $object;
           $object = $node;
 
         }
-        // Else we were unable to load the node
+        // Else we were unable to load the node.
         else {
 
           // Warn the administrator
@@ -947,14 +980,14 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
           else {
             tripal_report_error('tripal_chado', TRIPAL_NOTICE, 'chado_expand_var: There is no node for the current object: <pre>%object</pre>', array('%object' => print_r($object,TRUE)));
           }
-        } //end of if node
+        } //End of if node.
       }
-      // RECURSIVE CASE: check to see if the node to be expanded associates with a
-      // chado table within one of the nested objects.
+      // RECURSIVE CASE: check to see if the node to be expanded associates with 
+      // a chado table within one of the nested objects.
       else {
 
         // We need to recurse -the node to expand is one of the nested objects
-        // We assume it's a nested object if the field value is an object
+        // We assume it's a nested object if the field value is an object.
         foreach ((array) $object as $field_name => $field_value) {
           if (is_object($field_value)) {
             $object->{$field_name} = chado_expand_var(
@@ -963,11 +996,11 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
             $to_expand
             );
           }
-        } //end of for each field in the current object
+        } // End of for each field in the current object.
       }
       break;
 
-    // The $type to be expanded is not yet supported
+    // The $type to be expanded is not yet supported.
     default:
       tripal_report_error('tripal_chado', TRIPAL_ERROR, 'chado_expand_var: Unrecognized type (%type). Should be one of "field", "table", "node".',
         array('%type' => $type));
@@ -975,22 +1008,22 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
   }
 
   // Move expandable arrays downwards -------------------------------
-  // If the type was either table or foreign key then a new chado variable was generated
-  // this variable will have it's own expandable array's which need to be moved down
-  // and merged with the base objects expandable arrays
+  // If the type was either table or foreign key then a new chado variable was 
+  // generated this variable will have it's own expandable array's which need to
+  // be moved down and merged with the base objects expandable arrays.
 
   // Thus, check all nested objects for expandable arrays
-  // and if they have them, move them downwards
+  // and if they have them, move them downwards.
   foreach ( (array)$object as $field_name => $field_value) {
     if (is_object($field_value)) {
 
-      // The current nested object has expandable arrays
+      // The current nested object has expandable arrays.
       if (isset($field_value->expandable_fields)) {
 
-        // Move expandable fields downwards
+        // Move expandable fields downwards.
         if (isset($field_value->expandable_fields) and is_array($field_value->expandable_fields)) {
 
-          // If the current object has it's own expandable fields then merge them
+          // If the current object has it's own expandable fields then merge them.
           if (isset($object->expandable_fields)) {
             $object->expandable_fields = array_merge(
               $object->expandable_fields,
@@ -999,7 +1032,7 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
             unset($object->{$field_name}->expandable_fields);
 
           }
-          // Otherwise, just move the expandable fields downwards
+          // Otherwise, just move the expandable fields downwards.
           else {
             $object->expandable_fields = $object->{$field_name}->expandable_fields;
             unset($object->{$field_name}->expandable_fields);
@@ -1007,10 +1040,11 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
 
         }
 
-        // Move expandable foreign keys downwards
+        // Move expandable foreign keys downwards.
         if (isset($field_value->expandable_foreign_keys) and is_array($field_value->expandable_foreign_keys)) {
 
-          // If the current object has it's own expandable foreign keys then merge them
+          // If the current object has it's own expandable foreign keys then 
+          // merge them.
           if (isset($object->expandable_foreign_keys)) {
             $object->expandable_foreign_keys = array_merge(
               $object->expandable_foreign_keys,
@@ -1019,17 +1053,17 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
             unset($object->{$field_name}->expandable_foreign_keys);
 
           }
-          // Otherwise, just move the expandable foreign keys downwards
+          // Otherwise, just move the expandable foreign keys downwards.
           else {
             $object->expandable_foreign_keys = $object->{$field_name}->expandable_foreign_keys;
             unset($object->{$field_name}->expandable_foreign_keys);
           }
         }
 
-        // Move expandable tables downwards
+        // Move expandable tables downwards.
         if (isset($field_value->expandable_tables) and is_array($field_value->expandable_tables)) {
 
-          // If the current object has it's own expandable tables then merge them
+          // If the current object has it's own expandable tables then merge them.
           if (isset($object->expandable_tables)) {
             $object->expandable_tables = array_merge(
               $object->expandable_tables,
@@ -1038,17 +1072,17 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
             unset($object->{$field_name}->expandable_tables);
 
           }
-          // Otherwise, just move the expandable tables downwards
+          // Otherwise, just move the expandable tables downwards.
           else {
             $object->expandable_tables = $object->{$field_name}->expandable_tables;
             unset($object->{$field_name}->expandable_tables);
           }
         }
 
-        // Move expandable nodes downwards
+        // Move expandable nodes downwards.
         if (isset($field_value->expandable_nodes) and is_array($field_value->expandable_nodes)) {
 
-          // If the current object has it's own expandable tables then merge them
+          // If the current object has it's own expandable tables then merge them.
           if (isset($object->expandable_nodes)) {
             $object->expandable_nodes = array_merge(
               $object->expandable_nodes,
@@ -1057,7 +1091,7 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
             unset($object->{$field_name}->expandable_nodes);
 
           }
-          // Otherwise, just move the expandable tables downwards
+          // Otherwise, just move the expandable tables downwards.
           else {
             $object->expandable_nodes = $object->{$field_name}->expandable_nodes;
             unset($object->{$field_name}->expandable_nodes);
@@ -1069,20 +1103,20 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
 
   // Move extended array downwards ----------------------------------
   // This tells us what we have expanded (ie: that we succeeded)
-  // and is needed to remove the entry from the expandable array
+  // and is needed to remove the entry from the expandable array.
 
-  // If there is no expanded field in the current object then check any of the nested objects
-  // and move it down
+  // If there is no expanded field in the current object then check any of the 
+  // nested objects and move it down.
   if (!property_exists($object, 'expanded')) {
 
-    // It's a nested object if the value is an object
+    // It's a nested object if the value is an object.
     foreach ( (array)$object as $field_name => $field_value) {
       if (is_object($field_value)) {
 
-        // Check if the current nested object has an expanded array
+        // Check if the current nested object has an expanded array.
         if (isset($field_value->expanded)) {
 
-          // If so, then move it downwards
+          // If so, then move it downwards.
           $object->expanded = $field_value->expanded;
           unset($field_value->expanded);
         }
@@ -1091,10 +1125,11 @@ function chado_expand_var($object, $type, $to_expand, $table_options = array())
   }
 
   // Check again if there is an expanded field in the current object
-  // We check again because it might have been moved downwards above
+  // We check again because it might have been moved downwards above.
   if (property_exists($object, 'expanded')) {
 
-    // If so, then remove the expanded identifier from the correct expandable array
+    // If so, then remove the expanded identifier from the correct expandable 
+    // array..
     $expandable_name = 'expandable_' . $type . 's';
     if (property_exists($object, $expandable_name) and $object->{$expandable_name}) {
       $key_to_remove = array_search($object->expanded, $object->{$expandable_name});

tripal_chado_views/api/tripal_chado_views.api.inc

@@ -3,39 +3,50 @@
  * @file
  * API functions for Chado Views Integration
  */
+/**
+ * @defgroup tripal_chado_views_api Chado Views Integration
+ * @ingroup tripal_chado_api
+ * @{
+
+ * @}
+ */
 
 /**
  * Programatically enable view
  *
- * This should be used in a hook_menu definition as the callback to provide a link
- * to enable the view (first example). It can also be called directly if needed (second example).
+ * This should be used in a hook_menu definition as the callback to provide a 
+ * link to enable the view (first example). It can also be called directly if 
+ * needed (second example).
  * @code
- // Create a URL that when the user navigates there, a given view will be enabled.
- // You will still need to provide a link to this menu item somewhere appropriate (ie: an admin landing page).
- function mymodule_menu() {
- $items = array();
-
- // Create one of these for each of your default views
- $items['admin/tripal/<PATH-TO-YOUR-ADMIN-SECTION>/views/<VIEW-MACHINE-NAME>/enable'] = array(
- 'title' => 'Enable <VIEW-HUMAN-READABLE-NAME>',
- 'page callback' => 'tripal_enable_view',
- 'page arguments' => array('<VIEW-MACHINE-NAME>', '<PATH-TO-REDIRECT-TO-AFTERWARDS>'),
- 'access arguments' => array('<YOUR-PERMISSION-KEY>'),
- 'type' => MENU_CALLBACK,
- );
-
- return $items;
- }
-
- // Call this function directly to disable a view
- // The example shows enabling your own default view when your module is enabled.
- // This might be useful if you disable your view when your module is disabled.
- function mymodule_enable() {
-
- $view_name = '<VIEW-MACHINE-NAME>';
- tripal_enable_view($view_name);
-
- }
+ *  Create a URL that when the user navigates there, a given view will be 
+ *  enabled.
+ *  You will still need to provide a link to this menu item somewhere 
+ *  appropriate (ie: an admin landing page).
+ * 
+ * function mymodule_menu () {
+ * $items = array();
+ *
+ *  //Create one of these for each of your default views
+ *  $items['admin/tripal/<PATH-TO-YOUR-ADMIN-SECTION>/views/<VIEW-MACHINE-NAME>/enable'] = array(
+ *  'title' => 'Enable <VIEW-HUMAN-READABLE-NAME>',
+ *  'page callback' => 'tripal_enable_view',
+ *  'page arguments' => array('<VIEW-MACHINE-NAME>', '<PATH-TO-REDIRECT-TO-AFTERWARDS>'),
+ *  'access arguments' => array('<YOUR-PERMISSION-KEY>'),
+ * 'type' => MENU_CALLBACK,
+ *  );
+ * 
+ *  return $items;
+ * }
+ * 
+ *  Call this function directly to disable a view
+ *  The example shows enabling your own default view when your module is enabled.
+ *  This might be useful if you disable your view when your module is disabled.
+ * function mymodule_enable() {
+ * 
+ *  $view_name = '<VIEW-MACHINE-NAME>';
+ * tripal_enable_view($view_name);
+ * 
+ *  }
  * @endcode
  *
  * @param $view_name
@@ -43,7 +54,7 @@
  * @param $redirect_link
  *   The path to redirect to. FALSE if no redirect needed
  *
- * @ingroup tripal_views_api
+ * @ingroup tripal_chado_views_api
  */
 function tripal_enable_view($view_name, $redirect_link = FALSE) {
 
@@ -64,34 +75,40 @@ function tripal_enable_view($view_name, $redirect_link = FALSE) {
 /**
  * Programatically disable view.
  *
- * This should be used in a hook_menu definition as the callback to provide a link
- * to disable the view (first example). It can also be called directly if needed (second example).
+ * This should be used in a hook_menu definition as the callback to provide a 
+ * link to disable the view (first example). It can also be called directly if 
+ * needed (second example).
+ * 
  * @code
- // Create a URL that when the user navigates there, a given view will be disabled.
- // You will still need to provide a link to this menu item somewhere appropriate.
- function mymodule_menu() {
- $items = array();
-
- // Create one of these for each of your default views
- $items['admin/tripal/<PATH-TO-YOUR-ADMIN-SECTION>/views/<VIEW-MACHINE-NAME>/disable'] = array(
- 'title' => 'Disable <VIEW-HUMAN-READABLE-NAME>',
- 'page callback' => 'tripal_disable_view',
- 'page arguments' => array('<VIEW-MACHINE-NAME>', '<PATH-TO-REDIRECT-TO-AFTERWARDS>'),
- 'access arguments' => array('<YOUR-PERMISSION-KEY>'),
- 'type' => MENU_CALLBACK,
- );
-
- return $items;
- }
-
- // Call this function directly to disable a view
- // The example shows disabling your own default view when your module is uninstalled
- function mymodule_uninstall() {
-
- $view_name = '<VIEW-MACHINE-NAME>';
- tripal_disable_view($view_name);
-
- }
+ *  //Create a URL that when the user navigates there, a given view will be 
+ *  //disabled.
+ *  //You will still need to provide a link to this menu item somewhere 
+ *  //appropriate.
+ * 
+ * function mymodule_menu() {
+ * $items = array();
+ * 
+ *   //Create one of these for each of your default views
+ * $items['admin/tripal/<PATH-TO-YOUR-ADMIN-SECTION>/views/<VIEW-MACHINE-NAME>/disable'] = array(
+ * 'title' => 'Disable <VIEW-HUMAN-READABLE-NAME>',
+ * 'page callback' => 'tripal_disable_view',
+ * 'page arguments' => array('<VIEW-MACHINE-NAME>', '<PATH-TO-REDIRECT-TO-AFTERWARDS>'),
+ * 'access arguments' => array('<YOUR-PERMISSION-KEY>'),
+ * 'type' => MENU_CALLBACK,
+ * );
+ * 
+ * return $items;
+ * }
+ * 
+ *    //Call this function directly to disable a view
+ *    //The example shows disabling your own default view when your module is 
+ *    //uninstalled
+ *  function mymodule_uninstall() {
+ * 
+ * $view_name = '<VIEW-MACHINE-NAME>';
+ *  tripal_disable_view($view_name);
+ * 
+ * }
  * @endcode
  *
  * @param $view_name
@@ -99,7 +116,7 @@ function tripal_enable_view($view_name, $redirect_link = FALSE) {
  * @param $redirect_link
  *   The path to redirect to. FALSE if no redirect needed
  *
- * @ingroup tripal_views_api
+ * @ingroup tripal_chado_views_api
  */
 function tripal_disable_view($view_name, $redirect_link = FALSE) {
 
@@ -118,70 +135,76 @@ function tripal_disable_view($view_name, $redirect_link = FALSE) {
 }
 
 /**
- * Remove any drupal fields from a chado-based default view definition if chado is external.
+ * Remove any drupal fields from a chado-based default view definition if chado 
+ * is external.
  * This ensures compatibility with an external chado database.
  *
- * You should be calling this function in your hook_views_default_views(). This function
- * will only remove drupal tables if chado is external; thus you do not need to worry about
- * checking yourself. For example, the following is a good hook_views_default_views():
+ * You should be calling this function in your hook_views_default_views(). 
+ * This function will only remove drupal tables if chado is external; thus you 
+ * do not need to worry about checking yourself. For example, the following is 
+ * a good  hook_views_default_views():
+ * 
  * @code
- function mymodule_views_default_views() {
- $views = array();
-
- // NOTE: <VIEW-TYPE> describes the type of view:
- //     - 'admin' for views used for administration of your module
- //     - 'search' for views used to search data
- //     - 'list' for views used primarily as data listings
-
- // <VIEW-HUMAN-READABLE-NAME>
- $view = mymodule_defaultview_<VIEW-TYPE>_<VIEW-MACHINE-NAME>();
- $view = tripal_make_view_compatible_with_external($view);
- $views[$view->name] = $view;
-
- // <VIEW-HUMAN-READABLE-NAME>
- $view = mymodule_defaultview_<VIEW-TYPE>_<VIEW-MACHINE-NAME>();
- $view = tripal_make_view_compatible_with_external($view);
- $views[$view->name] = $view;
-
- return $views;
- }
-
- function mymodule_defaultview_<VIEW-TYPE>_<VIEW-MACHINE-NAME>() {
- // PASTE VIEWS EXPORT CODE HERE
- return $view;
- }
-
- function mymodule_defaultview_<VIEW-TYPE>_<VIEW-MACHINE-NAME>() {
- // PASTE VIEWS EXPORT CODE HERE
- return $view;
- }
+ * function mymodule_views_default_views() {
+ * $views = array();
+ * 
+ *   // NOTE: <VIEW-TYPE> describes the type of view:
+ *   //      - 'admin' for views used for administration of your module
+ *   //      - 'search' for views used to search data
+ *   //     - 'list' for views used primarily as data listings
+ *   //
+ *   //<VIEW-HUMAN-READABLE-NAME>
+ * $view = mymodule_defaultview_<VIEW-TYPE>_<VIEW-MACHINE-NAME>();
+ * $view = tripal_make_view_compatible_with_external($view);
+ * $views[$view->name] = $view;
+ * 
+ *    //<VIEW-HUMAN-READABLE-NAME>
+ * $view = mymodule_defaultview_<VIEW-TYPE>_<VIEW-MACHINE-NAME>();
+ * $view = tripal_make_view_compatible_with_external($view);
+ * $views[$view->name] = $view;
+ * 
+ * return $views;
+ * }
+
+ * function mymodule_defaultview_<VIEW-TYPE>_<VIEW-MACHINE-NAME>() {
+ *     //PASTE VIEWS EXPORT CODE HERE
+ * return $view;
+ * }
+ * 
+ * function mymodule_defaultview_<VIEW-TYPE>_<VIEW-MACHINE-NAME>() {
+ *    //PASTE VIEWS EXPORT CODE HERE
+ * return $view;
+ * }
  * @endcode
- * Notice that the actual views export code is in a separate function. This makes your
- * hook_views_default_views() more readable.
+ * Notice that the actual views export code is in a separate function. 
+ * This makes your hook_views_default_views() more readable.
  *
- * NOTE: Currently assumes all tables not in the tripal views integration tables are Drupal tables.
+ * NOTE: Currently assumes all tables not in the tripal views integration 
+ * tables are Drupal tables.
  *
  * @param $view
  *   The default view definition object
  * @return
- *   The default view with all relationships, fields, filters, sorts, arguments for
- *   Drupal tables removed.
+ *   The default view with all relationships, fields, filters, sorts, arguments 
+ *   for Drupal tables removed.
+ * 
+ * @ingroup tripal_chado_views_api
  */
 function tripal_make_view_compatible_with_external($view) {
   $remove_table = array();
 
   // First check that the base table for the view is a chado table
-  // If it's not then don't do any filtering
+  // If it's not then don't do any filtering.
   $setup_id = tripal_is_table_integrated($view->base_table);
   if (!$setup_id) {
     return $view;
   }
 
-  // IF chado is external then remove all config relating to drupal tables
+  // IF chado is external then remove all config relating to drupal tables.
   $is_local = isset($GLOBALS["chado_is_local"]) && $GLOBALS["chado_is_local"];
   if (!$is_local) {
 
-    // Iterate through all displays
+    // Iterate through all displays.
     foreach ($view->display as $display_name => $display) {
       $display_options = $display->handler->display->display_options;
 
@@ -189,13 +212,14 @@ function tripal_make_view_compatible_with_external($view) {
       foreach ($sections as $section) {
         $display_options[$section] = (isset($display_options[$section])) ? $display_options[$section] : array();
         foreach ($display_options[$section] as $key => $defn) {
-          // If the table has not already been encountered; check if it's in tripal_views
+          // If the table has not already been encountered; check if it's in 
+          // tripal_views.
           if (!isset($remove_table[ $defn['table'] ])) {
-            // If the table is view then this is a general handler; thus keep
+            // If the table is view then this is a general handler; thus keep.
             if ($defn['table'] == 'views') {
               $remove_table[ $defn['table'] ] = FALSE;
             }
-            // If this table is integrated then it is chado; thus keep
+            // If this table is integrated then it is chado; thus keep.
             $setup_id = tripal_is_table_integrated($defn['table']);
             if ($setup_id) {
               $remove_table[ $defn['table'] ] = FALSE;
@@ -205,7 +229,8 @@ function tripal_make_view_compatible_with_external($view) {
             }
           }
 
-          // Based on the $remove_table array, unset this field if its from a drupal table
+          // Based on the $remove_table array, unset this field if its from a 
+          // drupal table.
           if ($remove_table[ $defn['table'] ]) {
             unset($view->display[$display_name]->handler->display->display_options[$section][$key]);
           }
@@ -224,18 +249,18 @@ function tripal_make_view_compatible_with_external($view) {
  * and -10 is of highest priority.
  *
  * @param $table_name
- *   The name of the table to retrieve the setup ID for. This can be either a materialized
- *   view or a chado table
+ *   The name of the table to retrieve the setup ID for. This can be either a 
+ *   materialized view or a chado table
  *
  * @return
- *   returns the lowest priority.  If the table has not been integrated, a priority of 10
- *   is returned.
+ *   returns the lowest priority.  If the table has not been integrated, a 
+ *   priority of 10 is returned.
  *
  * @ingroup tripal_chado_views_api
  */
 function tripal_get_lightest_views_integration_priority($table_name) {
 
-  // D7 TODO: Check DBTNG changes work
+  // D7 TODO: Check DBTNG changes work.
   $sql = "SELECT priority FROM {tripal_views} WHERE table_name=:table ORDER BY priority ASC";
   $setup = db_query($sql, array(':table' => $table_name));
   $setup = $setup->fetchObject();
@@ -243,29 +268,31 @@ function tripal_get_lightest_views_integration_priority($table_name) {
     return $setup->priority;
   }
   else {
-    // default priority is 10
+    // Default priority is 10.
     return 10;
   }
 }
 
 /**
- * Retrieve the views integration setup_id with the lightest priority for a given table
+ * Retrieve the views integration setup_id with the lightest priority for a 
+ * given table
  *
  * NOTE: Uses lightest priority (drupal-style) where the range is from -10 to 10
  * and -10 is of highest priority.
  *
  * @param $table_name
- *   The name of the table to retrieve the setup ID for. This can be either a materialized
- *   view or a chado table
+ *   The name of the table to retrieve the setup ID for. This can be either a 
+ *   materialized view or a chado table
  *
  * @return
- *   On success, the setup_id to use for integration of this table; otherwise FALSE
+ *   On success, the setup_id to use for integration of this table; otherwise 
+ *   FALSE
  *
  * @ingroup tripal_chado_views_api
  */
 function tripal_get_lightest_views_integration_setup($table_name) {
 
-  // D7 TODO: Check DBTNG changes work
+  // D7 TODO: Check DBTNG changes work.
   $sql = "SELECT setup_id FROM {tripal_views} WHERE table_name=:table ORDER BY priority ASC";
   $setup = db_query($sql, array(':table' => $table_name));
   $setup = $setup->fetchObject();
@@ -278,16 +305,18 @@ function tripal_get_lightest_views_integration_setup($table_name) {
 }
 
 /**
- * Retrieve the views integration setup_id with the given priority/table combination.
+ * Retrieve the views integration setup_id with the given priority/table 
+ * combination.
  *
  * @param $table_name
- *   The name of the table to retrieve the setup ID for. This can be either a materialized
- *   view or a chado table
+ *   The name of the table to retrieve the setup ID for. This can be either a 
+ *   materialized view or a chado table
  * @param $priority
  *   The priority of the integration to retrieve the setup_id for
  *
  * @return
- *   On success, the setup_id to use for integration of this table; otherwise FALSE
+ *   On success, the setup_id to use for integration of this table; otherwise 
+ *   FALSE
  *
  * @ingroup tripal_chado_views_api
  */
@@ -306,7 +335,8 @@ function tripal_get_views_integration_setup_id($table_name, $priority) {
 }
 
 /**
- * Check to see if this table already has an integration record with the given priority.
+ * Check to see if this table already has an integration record with the given 
+ * priority.
  *
  * @param $table_name
  *   The name of the table to check for integration
@@ -315,21 +345,22 @@ function tripal_get_views_integration_setup_id($table_name, $priority) {
  *
  * @return
  *  If the table is already integrated, the setup_id of the existing integration
- *  record is returned (If priority is not specified this will be the lightest record);
- *  Otherwise the table is not already integrated and FALSE is returned.
+ *  record is returned (If priority is not specified this will be the lightest 
+ *  record);  Otherwise the table is not already integrated and FALSE is 
+ *  returned.
  *
  * @ingroup tripal_chado_views_api
  */
 function tripal_is_table_integrated($table_name, $priority = NULL) {
 
   if ($priority) {
-    // D7 TODO: Check DBTNG changes work
+    // D7 TODO: Check DBTNG changes work.
     $sql = "SELECT setup_id FROM {tripal_views} WHERE table_name=:table AND priority=:priority";
     $setup = db_query($sql, array(':table' => $table_name, ':priority' => $priority));
     $setup = $setup->fetchObject();
   }
   else {
-    // D7 TODO: Check DBTNG changes work
+    // D7 TODO: Check DBTNG changes work.
     $sql = "SELECT setup_id FROM {tripal_views} WHERE table_name=:table ORDER BY priority ASC";
     $setup = db_query($sql, array(':table' => $table_name));
     $setup = $setup->fetchObject();
@@ -343,8 +374,9 @@ function tripal_is_table_integrated($table_name, $priority = NULL) {
 }
 
 /**
- * Checks if you are dealing with the lightest priority setup for a given table. This is a
- * good way to determine whether your modules integration is being used by views.
+ * Checks if you are dealing with the lightest priority setup for a given table. 
+ * This is a good way to determine whether your modules integration is being 
+ * used by views.
  *
  * @param $setup_id
  *   The ID of the setup to check (is this setup the lightest one?)
@@ -370,11 +402,11 @@ function tripal_is_lightest_priority_setup($setup_id, $table_name) {
 /**
  * Rebuilds all the default integrations.
  *
- * This essentially clears the cache in case you mess up the integrations in your site.
- * This should not be used during module development since it really only rebuilds the
- * integrations described by all enabled modules in the site and if $delete_first is
- * TRUE it can delete custom integrations created by site administrators which will not
- * make your module popular.
+ * This essentially clears the cache in case you mess up the integrations in 
+ * your site. This should not be used during module development since it 
+ * really only rebuilds the integrations described by all enabled modules 
+ * in the site and if $delete_first is TRUE it can delete custom integrations 
+ * created by site administrators which will not make your module popular.
  *
  * @param $delete_first
  *   If TRUE then all integrations are first deleted.
@@ -397,59 +429,60 @@ function tripal_rebuild_views_integrations($delete_first = FALSE) {
 /**
  * Add views integration records into the tripal_views* tables.
  *
- * This is the programatic way to add your own integrations to the tripal views integrations
- * list. Keep in mind that the priority set in your $defn_array needs to be lighter than
- * any existing integrations to be used by views and that it should still be below 0
- * in order to allow site administrators to override it should they need to.
+ * This is the programatic way to add your own integrations to the tripal views 
+ * integrations list. Keep in mind that the priority set in your $defn_array 
+ * needs to be lighter than any existing integrations to be used by views and 
+ * that it should still be below 0 in order to allow site administrators to 
+ * override it should they need to.
  *
  * @param $defn_array
- *   An array describing the structure and fields of the table
+ *   An array describing the structure and fields of the table.
  *
  * @return
- *   True/False if completed successfully/not
+ *   True/False if completed successfully/not.
  *
  * Example usage (in hook_install()):
  * @code
-  $defn_array = array(
-    'table' => 'feature', //tablename or materialized view name
-    'name' => 'Sequence Features', // Human readable name
-    'type' => 'chado', //either chado or mview depending on tablename
-    'description' => 'Create a listing of features.', //description seen when creating a view of this type
-    'priority' => 10, //For Base tripal modules: 10; custom modules: 9 to 0;
-    'base_table' => TRUE //either TRUE or FALSE depending on whether the current table should show up in the add view list
-    'fields' => array(
-      'feature_id' => array(
-        'name' => 'feature_id', //field name in database
-        'title' => 'Feature ID', //human-readable name -seen in Views UI
-        'description' => 'This is the unique identifier for features', //help/description seen in Views UI
-        'type' => 'int', // the type of field
-        'handlers' => array(  //possible keys are field, filter, sort, argument, relationship
-          'field' => array(
-            'name' => 'chado_views_handler_numeric' //name of handler
-          ),
-          'filter' => array( ... ),
-          ...
-        ),
-        // Describe any joins involving this field.
-        // Note: you can include both foreign keys (feature.type_id => cvterm.cvterm_id)
-        // and referring tables (ie: feature.feature_id <= feature_relationship.subject_id)
-        'joins' => array(
-          'feature_relationship' => array( //table to join to.
-            'subject_id' => array( //field in above table (feature_relationship)
-              'table' => 'featureprop', //table to join to
-              'field' => 'feature_id', //field in above table (feature_relationship)
-              'handler' => 'views_join', //handler to use for joining
-              'relationship_handler' => 'views_handler_relationship', //handler to use when a relationship is added.
-              'relationship_only' => FALSE, //whether to join automatically (FALSE) or not (TRUE)
-            ),
-            ...
-          ),
-          ...
-        ),
-      )
-    ),
-  );
-  tripal_add_views_integration($defn_array);
+ *  $defn_array = array(
+ *    'table' => 'feature', //tablename or materialized view name
+ *    'name' => 'Sequence Features', // Human readable name
+ *    'type' => 'chado', //either chado or mview depending on tablename
+ *    'description' => 'Create a listing of features.', //description seen when creating a view of this type
+ *    'priority' => 10, //For Base tripal modules: 10; custom modules: 9 to 0;
+ *    'base_table' => TRUE //either TRUE or FALSE depending on whether the current table should show up in the add view list
+ *    'fields' => array(
+ *      'feature_id' => array(
+ *        'name' => 'feature_id', //field name in database
+ *        'title' => 'Feature ID', //human-readable name -seen in Views UI
+ *         'description' => 'This is the unique identifier for features', //help/description seen in Views UI
+ *         'type' => 'int', // the type of field
+ *        'handlers' => array(  //possible keys are field, filter, sort, argument, relationship
+ *           'field' => array(
+ *             'name' => 'chado_views_handler_numeric' //name of handler
+ *           ),
+ *           'filter' => array( ... ),
+ *           ...
+ *         ),
+ *        // Describe any joins involving this field.
+ *        // Note: you can include both foreign keys (feature.type_id => cvterm.cvterm_id)
+ *        // and referring tables (ie: feature.feature_id <= feature_relationship.subject_id)
+ *         'joins' => array(
+ *          'feature_relationship' => array( //table to join to.
+ *            'subject_id' => array( //field in above table (feature_relationship)
+ *              'table' => 'featureprop', //table to join to
+ *              'field' => 'feature_id', //field in above table (feature_relationship)
+ *              'handler' => 'views_join', //handler to use for joining
+ *              'relationship_handler' => 'views_handler_relationship', //handler to use when a relationship is added.
+ *              'relationship_only' => FALSE, //whether to join automatically (FALSE) or not (TRUE)
+ *            ),
+ *            ...
+ *          ),
+ *          ...
+ *         ),
+ *      )
+ *    ),
+ *  );
+ *  tripal_add_views_integration($defn_array);
  * @endcode
  *
  * @ingroup tripal_chado_views_api
@@ -463,7 +496,7 @@ function tripal_add_views_integration($defn_array, $setup_id = FALSE) {
     return $no_errors;
   }
 
-  // First insert into tripal_views
+  // First insert into tripal_views.
   $view_record = array(
     'table_name' => $defn_array['table'],
     'name' => $defn_array['name'],
@@ -512,7 +545,7 @@ function tripal_add_views_integration($defn_array, $setup_id = FALSE) {
     // Need to update the tripal_views record so base_table can be false
     // this is a fix because drupal_write_record() puts in defaults if !isset()
     // and a variable is considered not set if it's null!
-    // D7 TODO: Check DBTNG changes work
+    // D7 TODO: Check DBTNG changes work.
     db_query(
       "UPDATE {tripal_views} SET base_table=:base WHERE table_name=:table AND priority=:priority",
       array(
@@ -522,7 +555,7 @@ function tripal_add_views_integration($defn_array, $setup_id = FALSE) {
       )
     );
 
-    // Insert Field Definitions
+    // Insert Field Definitions.
     foreach ($defn_array['fields'] as $key => $field) {
       // Set some defaults.
       $field['name'] = (isset($field['name'])) ? $field['name'] : $key;
@@ -541,7 +574,7 @@ function tripal_add_views_integration($defn_array, $setup_id = FALSE) {
       );
       if ($view_record['setup_id'] && $field['name'] && $field['title'] && $field['description'] && $field['type']) {
         if (isset($defn_array['additional_content'])) {
-          // D7 TODO: Check DBTNG changes work
+          // D7 TODO: Check DBTNG changes work.
           $is_present = db_query(
             "SELECT true as present FROM {tripal_views_field} WHERE column_name=:column AND setup_id=:setup",
             array(
@@ -568,7 +601,7 @@ function tripal_add_views_integration($defn_array, $setup_id = FALSE) {
 
       if ($status) {
 
-        // Insert Handler Definitions
+        // Insert Handler Definitions.
         foreach ($field['handlers'] as $handler_type => $handler) {
           $handler_record = array(
             'setup_id' => $view_record['setup_id'],
@@ -608,7 +641,7 @@ function tripal_add_views_integration($defn_array, $setup_id = FALSE) {
             );
           }
 
-          // Loop on left fields
+          // Loop on left fields.
           foreach ($joins as $left_field => $join) {
             $join_record = array(
               'setup_id' => $view_record['setup_id'],
@@ -675,7 +708,8 @@ function tripal_add_views_integration($defn_array, $setup_id = FALSE) {
  *   The unique setup id of the tripal views integration
  *
  * @return
- *   A views integration definition array as used by tripal_add_views_integration()
+ *   A views integration definition array as used by 
+ *   tripal_add_views_integration()
  *
  * @ingroup tripal_chado_views_api
  */
@@ -695,7 +729,7 @@ function tripal_export_views_integration($setup_id) {
     'fields' => array(),
   );
 
-  // Add fields
+  // Add fields.
   $resource = db_query("SELECT * FROM {tripal_views_field} WHERE setup_id=:setup", array(':setup' => $setup_id));
   foreach ($resource as $r) {
     $defn_array['fields'][ $r->column_name ] = array(
@@ -708,7 +742,7 @@ function tripal_export_views_integration($setup_id) {
     );
   }
 
-  // Add handlers
+  // Add handlers.
   $resource = db_query("SELECT * FROM {tripal_views_handlers} WHERE setup_id=:setup", array(':setup' => $setup_id));
   foreach ($resource as $r) {
     $defn_array['fields'][ $r->column_name ]['handlers'][ $r->handler_type ] = array(
@@ -716,7 +750,7 @@ function tripal_export_views_integration($setup_id) {
     );
   }
 
-  // Add joins
+  // Add joins.
   $resource = db_query("SELECT * FROM {tripal_views_join} WHERE setup_id=:setup", array(':setup' => $setup_id));
   foreach ($resource as $r) {
     $defn_array['fields'][ $r->base_field ]['joins'][ $r->left_table ][ $r->left_field ] = array(
@@ -730,31 +764,32 @@ function tripal_export_views_integration($setup_id) {
 }
 
 /**
- * Removes a View Integration Entry when you only know the table the integration was
- * created for and the priority.
+ * Removes a View Integration Entry when you only know the table the integration 
+ * was created for and the priority.
  *
- * This should only be used to remove integrations created by your own module (possibly
- * on uninstall of your module). To override existing integrations simply create your own
- * integration with a lighter priority using tripal_clone_views_integration() or
- * tripal_export_views_integration() to create a template.
+ * This should only be used to remove integrations created by your own module 
+ * (possibly on uninstall of your module). To override existing integrations 
+ * simply create your own integration with a lighter priority using 
+ * tripal_clone_views_integration() or tripal_export_views_integration() to 
+ * create a template.
  *
  * @param $identifies
- *   An array of identifiers where the keys indicate what the identifier is. One of the
- *   following compinations must be present:
- *    1) table_name & priority: the name of the table & the priority to remove a views
- *       integration entry for
- *    2) setup_id: the setup_id of the entry to remove
+ *   An array of identifiers where the keys indicate what the identifier is. 
+ *   One of the following compinations must be present:
+ *    1) table_name & priority: the name of the table & the priority to remove 
+ *        a views integration entry for.
+ *    2) setup_id: the setup_id of the entry to remove.
  * @param $options
- *   An array of options, currently none are supported
+ *   An array of options, currently none are supported.
  *
  * @return
- *   TRUE on Success; FALSE otherwise
+ *   TRUE on Success; FALSE otherwise.
  *
  * @ingroup tripal_chado_views_api
  */
 function tripal_remove_views_integration($identifiers, $options = array()) {
 
-  // Remove the views integration using the table_name/priority combo
+  // Remove the views integration using the table_name/priority combo.
   if (isset($identifiers['table_name'])) {
     $table_name = $identifiers['table_name'];
     $priority = $identifiers['priority'];
@@ -773,7 +808,7 @@ function tripal_remove_views_integration($identifiers, $options = array()) {
 
   }
 
-  // Remove the views integration using the setup_id
+  // Remove the views integration using the setup_id.
   if (isset($identifiers['setup_id'])) {
 
     db_query('DELETE FROM {tripal_views} WHERE setup_id=:setup', array(':setup' => $identifiers['setup_id']));
@@ -808,18 +843,20 @@ function tripal_update_views_integration($setup_id, $defn_array) {
 }
 
 /**
- * Clone an integration. This is often a great way to create your own module-specific
- * integration while still benifiting from an existing (or even the lightest priority)
- * integration.
+ * Clone an integration. This is often a great way to create your own 
+ * module-specific integration while still benifiting from an existing 
+ * (or even the lightest priority) integration.
  *
  * @param $table_name
  *   The table for which you'd like to clone an integration
  * @param $new_priority
  *   The priority of the clone; this is the integration which will be created.
- *   If no priority is supplied then one lighter then the $template_priority will be used.
+ *   If no priority is supplied then one lighter then the $template_priority 
+ *   will be used.
  * @param $template_priority
- *   The priority of the template to be used for the clone; this is an existing integration.
- *   If no priority is supplied then the lightest priority will be used.
+ *   The priority of the template to be used for the clone; this is an existing 
+ *   integration. If no priority is supplied then the lightest priority will be 
+ *   used.
  *
  * @ingroup tripal_chado_views_api
  */
@@ -864,18 +901,21 @@ function tripal_clone_views_integration($table_name, $new_priority = NULL, $temp
 }
 
 /**
- * Adds the given field to an existing or cloned integration. In the case of a cloned
- * integration, the lightest integration is used as the template for the clone.
+ * Adds the given field to an existing or cloned integration. In the case of a
+ * cloned integration, the lightest integration is used as the template for the 
+ * clone.
  *
- * NOTE: If that field already exists in the specified integration then it will first be
- * deleted and the new one added.
+ * NOTE: If that field already exists in the specified integration then it will 
+ * first be deleted and the new one added.
  *
  * @param $table_name
  *   The name of the table the integration is for
  * @param $priority
- *   The priority of the integration to use; pass NULL to use the lightest integration
+ *   The priority of the integration to use; pass NULL to use the lightest 
+ *   integration
  * @param $field
- *   An array describing the field ot add; uses the same format as the $defn_array
+ *   An array describing the field ot add; uses the same format as the
+ *   $defn_array
  *
  * @return
  *   TRUE if the field was added successfully; FALSE otherwise
@@ -885,7 +925,7 @@ function tripal_clone_views_integration($table_name, $new_priority = NULL, $temp
 function tripal_add_field_to_views_integration($table_name, $priority, $field) {
   $no_errors = TRUE;
 
-  // If no priority is supplied then add the field to the lightest integration
+  // If no priority is supplied then add the field to the lightest integration.
   if (empty($priority)) {
     $priority = tripal_get_lightest_views_integration_priority($table_name);
   }
@@ -902,7 +942,7 @@ function tripal_add_field_to_views_integration($table_name, $priority, $field) {
   $setup_id = $setup_id->fetchObject();
 
   // If there isn't an integration matching that table/priority combination
-  // then clone the lightest priority integration
+  // then clone the lightest priority integration.
   if (empty($setup_id)) {
     $setup_id = tripal_clone_views_integration($table_name, $priority);
   }
@@ -918,7 +958,7 @@ function tripal_add_field_to_views_integration($table_name, $priority, $field) {
     array(':setup' => $setup_id, ':table' => $table_name, ':field' => $field['name'])
   );
 
-  // Now we need to add/update the field
+  // Now we need to add/update the field.
   $field_record = array(
     'setup_id' => $setup_id,
     'column_name' => $field['name'],
@@ -928,7 +968,7 @@ function tripal_add_field_to_views_integration($table_name, $priority, $field) {
   );
   if ($setup_id && $field['name'] && $field['title'] && $field['description'] && $field['type']) {
     if ($defn_array['additional_content']) {
-      // D7 TODO: Check DBTNG changes work
+      // D7 TODO: Check DBTNG changes work.
       $is = db_query(
         "SELECT true as present FROM {tripal_views_field} WHERE column_name=:column AND setup_id=:setup",
         array(':column' => $field_record['column_name'], ':setup' => $field_record['setup_id'])
@@ -952,7 +992,7 @@ function tripal_add_field_to_views_integration($table_name, $priority, $field) {
 
   if ($status) {
 
-    // Insert Handler Definitions
+    // Insert Handler Definitions.
     foreach ($field['handlers'] as $handler_type => $handler) {
       $handler_record = array(
         'setup_id' => $setup_id,
@@ -992,7 +1032,7 @@ function tripal_add_field_to_views_integration($table_name, $priority, $field) {
         );
       }
 
-      // Loop on left fields
+      // Loop on left fields.
       foreach ($joins as $left_field => $join) {
         $join_record = array(
           'setup_id' => $setup_id,
@@ -1043,20 +1083,22 @@ function tripal_add_field_to_views_integration($table_name, $priority, $field) {
 }
 
 /**
- * Adds the given field to an existing or cloned integration. In the case of a cloned
- * integration, the lightest integration is used as the template for the clone.
+ * Adds the given field to an existing or cloned integration. In the case of a
+ * cloned integration, the lightest integration is used as the template for the
+ * clone.
  *
- * NOTE: If that field already exists in the specified integration then it will first be
- * deleted and the new one added.
+ * NOTE: If that field already exists in the specified integration then it will
+ * first be deleted and the new one added.
  *
  * @param $table_name
  *   The name of the table the integration is for
  * @param $priority
- *   The priority of the integration to use; pass NULL to use the lightest integration
+ *   The priority of the integration to use; pass NULL to use the lightest
+ *   integration
  * @param $field
  *   An array describing the join to add. it should contain the following keys:
- *   base_table, base_field, left_table, left_field, handler, relationship_handler,
- *   relationship_only
+ *   base_table, base_field, left_table, left_field, handler, 
+ *   relationship_handler, relationship_only
  *
  * @return
  *   TRUE if the field was added successfully; FALSE otherwise
@@ -1066,12 +1108,12 @@ function tripal_add_field_to_views_integration($table_name, $priority, $field) {
 function tripal_add_join_to_views_integration($table_name, $priority, $join) {
   $no_errors = TRUE;
 
-  // If no priority is supplied then add the field to the lightest integration
+  // If no priority is supplied then add the field to the lightest integration.
   if (empty($priority)) {
     $priority = tripal_get_lightest_views_integration_priority($table_name);
   }
 
-  // First get the setup_id
+  // First get the setup_id.
   $setup_id = db_query(
     "SELECT setup_id FROM {tripal_views} WHERE table_name=:table AND priority=:priority",
     array(
@@ -1082,7 +1124,7 @@ function tripal_add_join_to_views_integration($table_name, $priority, $join) {
   $setup_id = $setup_id->fetchField();
 
   // If there isn't an integration matching that table/priority combination
-  // then clone the lightest priority integration
+  // then clone the lightest priority integration.
   if (empty($setup_id)) {
     $setup_id = tripal_clone_views_integration($table_name, $priority);
   }
@@ -1094,19 +1136,19 @@ function tripal_add_join_to_views_integration($table_name, $priority, $join) {
 }
 
 /**
- * Remove a join from an integration. This is usually done after cloning an existing
- * integration using tripal_clone_views_integration().
+ * Remove a join from an integration. This is usually done after cloning an 
+ * existing integration using tripal_clone_views_integration().
  *
  * @param $setup_id
- *   The setup_id of the integration to delete the join from
+ *   The setup_id of the integration to delete the join from.
  * @param $base_table
- *   The name of the base table involved the join
+ *   The name of the base table involved the join.
  * @param $base_field
- *   The field from the base table involved in the join
+ *   The field from the base table involved in the join.
  * @param $left_table
  *   The name of the other table involved in the join
  * @param $left_field
- *   The name of the field from the other table involved in the join
+ *   The name of the field from the other table involved in the join.
  *
  * @ingroup tripal_chado_views_api
  */

tripal_ds/api/tripal_ds.pane.api.inc

@@ -30,6 +30,9 @@
  *  field_create_field($field);
  *  field_create_instance($instance);
  *  tripal_ds_field_create_field($field_label, $field, $bundle);
+ * 
+ *  @ingroup tripal_ds_pane_api
+ * 
  */
 function tripal_ds_create_field($field_label, $field_name, $bundle_name) {
   $field_name = str_replace(' ', '_', strtolower($field_name));

tripal_ws/api/tripal_ws.api.inc

@@ -10,9 +10,10 @@
  * @defgroup tripal_ws_api Web Services
  *
  * @ingroup tripal_api
+ * {@
  * The Tripal Web Services API provides a set of functions for interacting
  * with the Tripal Web Services.
- *
+ * @}
  */
 
 /**
@@ -59,6 +60,8 @@ function hook_tripal_ws_value(&$items, $field, $instance) {
  *
  * @return
  *   A list of TripalWebService names.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_get_web_services() {
   $services = array();
@@ -88,6 +91,8 @@ function tripal_get_web_services() {
  *
  * @return
  *   TRUE if the field type class file was found, FALSE otherwise.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_load_include_web_service_class($class) {
 
@@ -119,6 +124,8 @@ function tripal_load_include_web_service_class($class) {
  *
  * @return
  *   TRUE if the site is successfully added, FALSE otherwise.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_add_site($name, $url, $version, $description) {
   $check_url = NULL;
@@ -173,6 +180,8 @@ function tripal_add_site($name, $url, $version, $description) {
  *
  * @return
  *   TRUE if the record was successfully deleted, FALSE otherwise.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_remove_site($record_id) {
   if ($record_id) {
@@ -199,6 +208,8 @@ function tripal_remove_site($record_id) {
  *
  * @return
  *   The JSON response formatted in a PHP array or FALSE if a problem occured.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_get_remote_content($site_id, $path = '', $query = '') {
 
@@ -278,6 +289,8 @@ function tripal_get_remote_content($site_id, $path = '', $query = '') {
  * @return
  *   The JSON-LD context mapping array, or FALSE if the context could not
  *   be retrieved.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_get_remote_context($context_url, $cache_id) {
 
@@ -327,6 +340,8 @@ function tripal_get_remote_context($context_url, $cache_id) {
  *   the Class (i.e. content type).
  * @return
  *   The JSON-LD context mapping array.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_get_remote_content_context($site_id, $context_url, $bundle_accession, $field_accession = '') {
   $cache_id = substr('trp_ws_context_' . $site_id . '-' . $bundle_accession . '-' . $field_accession, 0, 254);
@@ -343,6 +358,8 @@ function tripal_get_remote_content_context($site_id, $context_url, $bundle_acces
  *
  * @param $site_id
  *   The numeric site ID for the remote Tripal site.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_clear_remote_cache($site_id) {
   if (!$site_id) {
@@ -359,6 +376,8 @@ function tripal_clear_remote_cache($site_id) {
  * @return
  *   The vocabulary of a remote Tripal web service, or FALSE if an error
  *   occured.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_get_remote_API_doc($site_id) {
   $site_doc = '';
@@ -445,6 +464,8 @@ function tripal_get_remote_API_doc($site_id) {
  * @return
  *    An array of fake entity objects where the key is the entity_id and
  *    the value is the object.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_load_remote_entities($remote_entity_ids, $site_id, $bundle_accession, $field_ids) {
 
@@ -534,6 +555,8 @@ function tripal_load_remote_entities($remote_entity_ids, $site_id, $bundle_acces
  *   be added to the entity returned.
  * @return
  *    A fake entity object.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_load_remote_entity($remote_entity_id, $site_id, $bundle_accession, $field_ids) {
 
@@ -639,6 +662,8 @@ function tripal_load_remote_entity($remote_entity_id, $site_id, $bundle_accessio
  *   The field array as returned by web services.
  * @param $context
  *   The web service JSON-LD context for the bundle to which the field belongs.
+ * 
+ * @ingroup tripal_ws_api
  */
 function _tripal_update_remote_entity_field($field_data, $context, $depth = 0) {
 
@@ -701,6 +726,8 @@ function _tripal_update_remote_entity_field($field_data, $context, $depth = 0) {
  * @return
  *   An array similar to that returned by the field_info_field function
  *   of Drupal for local fields.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_get_remote_field_info($site_id, $bundle_accession, $field_accession){
 
@@ -741,6 +768,8 @@ function tripal_get_remote_field_info($site_id, $bundle_accession, $field_access
  * @return
  *   An array similar to that returned by the field_info_instance function
  *   of Drupal for local fields.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_get_remote_field_instance_info($site_id, $bundle_accession, $field_accession){
 
@@ -784,6 +813,8 @@ function tripal_get_remote_field_instance_info($site_id, $bundle_accession, $fie
  * @return
  *   A PHP array corresponding to the Hydra Class stanza (i.e. a content type).
  *   Returns NULL if the class ID cannot be found.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_get_remote_content_doc($site_id, $bundle_accession){
 
@@ -819,6 +850,8 @@ function tripal_get_remote_content_doc($site_id, $bundle_accession){
  *   A PHP array corresponding to the Hydra property stanza (field) that
  *   belongs to the given Class (i.e. a content type).  Retruns NULL if the
  *   property cannot be found.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_get_remote_field_doc($site_id, $bundle_accession, $field_accession){
 
@@ -855,6 +888,8 @@ function tripal_get_remote_field_doc($site_id, $bundle_accession, $field_accessi
  * @return
  *   An array of field downloader class names that are compoatible with the
  *   field and which exist on this site.
+ * 
+ * @ingroup tripal_ws_api
  */
 function tripal_get_remote_field_formatters($site_id, $bundle_accession, $field_accession) {