Resulved issue #332

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

@@ -1,7 +1,7 @@
 <?php
 /**
  * @file
- * Provides functions for managing analysis'.
+ * Provides API functions specificially for managing analysis records in Chado.
  *
  * @ingroup tripal_chado
  */
@@ -10,7 +10,8 @@
  * @defgroup tripal_analysis_api Chado Analysis
  * @ingroup tripal_chado_api
  * @{
-
+ * Provides API functions for working with analysis records in Chado that
+ * go beyond the generic Chado API functions.
  * @}
  */
 
@@ -28,15 +29,14 @@
  *      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.
+ *   NOTE: the $identifier parameter can be any array similar to $values 
+ *   passed into chado_select_record(). It should fully specify the stock record 
+ *   to be returned.
  * @param $options
  *   An array of options. Supported keys include:
  *     - 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.
- *
  * @return
  *   the analysis node matching the passed in identifier
  *

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

@@ -1,7 +1,7 @@
 <?php
 /**
  * @file
- * Functions to interact with contacts.
+ * Provides API functions specificially for managing contact records in Chado.
  *
  * @ingroup tripal_chado
  */
@@ -10,6 +10,8 @@
  * @defgroup tripal_contact_api Chado Contact
  * @ingroup tripal_chado_api
  * @{
+ * Provides API functions for working with chado records in Chado that
+ * go beyond the generic Chado API functions.
  * @}
  */
 

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

@@ -1,9 +1,9 @@
 <?php
 /**
  * @file
- * This module provides a set of functions to simplify working with
- * controlled vocabularies.
- *
+ * Provides API functions specificially for managing controlled vocabulary
+ * records in Chado.  
+ * 
  * @ingroup tripal_chado
  */
 
@@ -11,6 +11,12 @@
  * @defgroup tripal_chado_cv_api Chado CV
  * @ingroup tripal_chado_api
  * @{
+ * Provides API functions specificially for managing controlled vocabulary
+ * records in Chado. Please note that Tripal v3 provides a generic set of 
+ * API functions for working with controlled vocabularies (CVs). This allows for
+ * CVs to be stored using any back-end.  By default CV's continue to be housed
+ * in Chado.  Therefore, if you are working directly with controlled vocabulary
+ * records inside of a Chado-aware module then these functions can be used. 
  * @}
  */
 

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

@@ -1,14 +1,21 @@
 <?php
 /**
  * @file
- * Provides an application programming interface (API) to manage references to
- * external databases
+ * Provides API functions specificially for managing external database reference
+ * records in Chado. 
  */
 
 /**
  * @defgroup tripal_chado_database_api Chado DB
  * @ingroup tripal_chado_api
  * @{
+ * External databases can be used to indicate the source for a variety of data.
+ * The most common use is with controlled vocabularies (CV).  Chado expects that
+ * every CV have an external database record, where the database name must be
+ * the short name of the CV.  In other cases, records such as features, stocks,
+ * libraries, etc., can also be present in remote databases and these
+ * associations can be made through dbxref linker tables.  The API functions
+ * provided here provide tools to easily work with external databases.
  * @}
  */
 
@@ -22,6 +29,7 @@
  *   );
  *   $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 (

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

@@ -1,13 +1,17 @@
 <?php
 /**
  * @file
- * Provides an application programming interface (API) for working with features
+ * Provides API functions specificially for managing feature
+ * records in Chado.  
  */
 
 /**
  * @defgroup tripal_feature_api Chado Feature
  * @ingroup tripal_chado_api
  * @{
+ * Provides API functions specificially for managing feature
+ * records in Chado especially retrieving relationships and sequences derived 
+ * from relationships and feature alignments.
  * @}
  */
 /**
@@ -1038,10 +1042,10 @@ function chado_get_featureloc_sequences($feature_id, $featurelocs) {
       // now sort the parts
       // if we're on the reverse strand we need to resort
       if ($featureloc->strand >= 0) {
-        usort($parts, 'chado_feature__residues_sort_rel_parts_by_start');
+        usort($parts, '_chado_feature__residues_sort_rel_parts_by_start');
       }
       else {
-        usort($rparts, 'chado_feature__residues_sort_rel_parts_by_start');
+        usort($rparts, '_chado_feature__residues_sort_rel_parts_by_start');
         $parts = $rparts;
       }
 
@@ -1256,7 +1260,7 @@ function chado_get_featurelocs($feature_id, $side = 'as_parent', $aggregate = 1)
     }
   }
 
-  usort($featurelocs, 'chado_feature__residues_sort_locations');
+  usort($featurelocs, '_chado_feature__residues_sort_locations');
   return $featurelocs;
 }
 
@@ -1351,9 +1355,8 @@ function _tripal_feature_load_relationships($feature_id, $side = 'as_subject') {
  * @param $a
  * @param $b
  * 
- * @ingroup tripal_feature_api
  */
-function chado_feature__residues_sort_rel_parts_by_start($a, $b) {
+function _chado_feature__residues_sort_rel_parts_by_start($a, $b) {
   foreach ($a as $type_name => $details) {
     $astart = $a[$type_name]['start'];
     break;
@@ -1375,9 +1378,8 @@ function chado_feature__residues_sort_rel_parts_by_start($a, $b) {
  * @return
  *   Which feature location comes first.
  *
- * @ingroup tripal_feature_api
  */
-function chado_feature__residues_sort_locations($a, $b) {
+function _chado_feature__residues_sort_locations($a, $b) {
   return strnatcmp($a->fmin, $b->fmin);
 }
 

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

@@ -1,13 +1,16 @@
 <?php
 /**
  * @file
- * Provides an application programming interface (API) to manage organisms
+ * Provides API functions specificially for managing feature
+ * records in Chado.  
  */
 
 /**
  * @defgroup tripal_organism_api Chado Organism
  * @ingroup tripal_chado_api
  * @{
+ * Provides API functions specificially for managing organism
+ * records in Chado.
  * @}
  */
 

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

@@ -2,13 +2,18 @@
 
 /**
  * @file
- * Provides an application programming interface (API) to manage organisms
+ * Provides API functions specificially for managing phylogenetic and taxonomic
+ * tree records in Chado.  
  */
 
 /**
  * @defgroup tripal_phylotree_api Chado Phylotree
  * @ingroup tripal_chado_api
  * @{
+ * Provides API functions specificially for managing phylogenetic and taxonomic
+ * tree records in Chado.  The API consists of functions for creation, 
+ * retrieval, update and deltion (CRUD) for phylogenetic tree records as 
+ * well as importing of trees in the newick file format.
  * @}
  */
 

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

@@ -1,13 +1,16 @@
 <?php
 /**
  * @file
- * Provides an application programming interface (API) to manage chado publications
+ * Provides API functions specificially for managing publication 
+ * records in Chado.  
  */
 
 /**
  * @defgroup tripal_pub_api Chado Publication
  * @ingroup tripal_chado_api
  * @{
+ * Provides API functions specificially for managing publication 
+ * records in Chado.
  * @}
  */
 

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

@@ -1,13 +1,19 @@
 <?php
 /**
  * @file
- * Provides an application programming interface (API) to manage stocks
+ * Provides API functions specificially for managing stock 
+ * records in Chado. 
  */
 
 /**
  * @defgroup tripal_stock_api Chado Stock
  * @ingroup tripal_chado_api
  * @{
+ * Provides API functions specificially for managing stock 
+ * records in Chado.  The stock table of Chado is used for storing a variety
+ * of data types besides just stocks from a stock collection.  Examples of 
+ * other records commonly stored in the stock table are germplasm and
+ * individuals from a breeding population.
  * @}
  */
 

tripal_chado/api/tripal_chado.api.inc

@@ -3,18 +3,23 @@
 /**
  * @file
  *
- * This file provides the Chado API: a set of functions for
- * interacting with Chado.
+ * This file contains miscellaneous API functions specific to working with
+ * records in Chado that do not have a home in any other sub category of 
+ * API functions.
  */
 
 /**
  * @defgroup tripal_chado_api Chado
  *
  * @ingroup tripal_api
- * The Tripal Chado API: a set of functions for
- * interacting with Chado.
- *
+ * The Tripal Chado API is a set of functions for interacting with data 
+ * inside of a Chado relational database. Entities (or pages) in Drupal
+ * that are provided by Tripal can supply data from any supported database 
+ * back-end, and Chado is the default. This API contains a variety of sub
+ * categories (or groups) where functions are organized.  Any extension module
+ * that desires to work with data in Chado will find these functions useful.
  */
+
 /**
  * Publishes content in Chado as a new TripalEntity entity.
  *

tripal_chado_views/api/tripal_chado_views.api.inc

@@ -1,13 +1,19 @@
 <?php
 /**
  * @file
- * API functions for Chado Views Integration
+ * Provides API functions that support direct integration of Chado tables with
+ * Drupal Views. 
  */
 /**
  * @defgroup tripal_chado_views_api Chado Views Integration
  * @ingroup tripal_chado_api
  * @{
-
+ * Provides API functions that support direct integration of Chado tables with
+ * Drupal Views. This is different from the entity and field integration that
+ * Tripal v3 provides.  Here Chado tables are directly integrated.  Tripal
+ * provides a web interface that allows site developers to customize how a
+ * Chado table is integrate with Views.  However, these functions provide
+ * programmatic access to the same functionality.
  * @}
  */