Working on updating in-line documenation for Tv3 API release

docs/tripal_doxygen.config

@@ -216,7 +216,7 @@ SEPARATE_MEMBER_PAGES  = NO
 # uses this value to replace tabs by spaces in code fragments.
 # Minimum value: 1, maximum value: 16, default value: 4.
 
-TAB_SIZE               = 8
+TAB_SIZE               = 2
 
 # This tag can be used to specify a number of aliases that act as commands in
 # the documentation. An alias has the form:
@@ -559,7 +559,7 @@ SORT_MEMBER_DOCS       = YES
 # this will also influence the order of the classes in the class list.
 # The default value is: NO.
 
-SORT_BRIEF_DOCS        = NO
+SORT_BRIEF_DOCS        = YES 
 
 # If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the
 # (brief and detailed) documentation of class members so that constructors and
@@ -571,14 +571,14 @@ SORT_BRIEF_DOCS        = NO
 # detailed member documentation.
 # The default value is: NO.
 
-SORT_MEMBERS_CTORS_1ST = NO
+SORT_MEMBERS_CTORS_1ST = YES
 
 # If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy
 # of group names into alphabetical order. If set to NO the group names will
 # appear in their defined order.
 # The default value is: NO.
 
-SORT_GROUP_NAMES       = NO
+SORT_GROUP_NAMES       = YES
 
 # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by
 # fully-qualified names, including namespaces. If set to NO, the class list will
@@ -604,7 +604,7 @@ STRICT_PROTO_MATCHING  = NO
 # list. This list is created by putting \todo commands in the documentation.
 # The default value is: YES.
 
-GENERATE_TODOLIST      = NO
+GENERATE_TODOLIST      = YES
 
 # The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test
 # list. This list is created by putting \test commands in the documentation.

tripal_bulk_loader/api/tripal_bulk_loader.api.templates.inc

@@ -7,7 +7,7 @@
  */
 
 /**
- * @defgroup tripal_bulk_loader_api Tripal Bulk Loader Module API
+ * @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

tripal_chado/api/tripal_chado.api.inc

@@ -15,6 +15,8 @@
  * @return boolean
  *   TRUE if all of the records of the given bundle type were published, and
  *   FALSE if a failure occured.
+ *
+ * @ingroup tripal_chado_api
  */
 function tripal_chado_publish_records($values, $job_id = NULL) {
 
@@ -354,79 +356,3 @@ function tripal_replace_chado_tokens($string, $record) {
   }
   return $string;
 }
-
-/**
- * Retrieve an entity_id for a chado record.
- *
- * @param string $chado_table
- *   The chado_table where the record is stored.
- * @param integer $record_id
- *   The record_id which is the primary key of the chado table.
- *
- * @return
- *   Return an integer representing the entity_id or NULL if not found. The
- *   record is then accessible on the website through URL /bio_data/<entity_id>
- */
-function tripal_get_chado_entity_id ($chado_table, $record_id) {
-  // To find the bundle_table, check if type_column is used for the chado table.
-  $type_column =
-    db_select('chado_bundle', 'CB')
-    ->fields('CB', array('type_column'))
-    ->condition('data_table', $chado_table)
-    ->execute()
-    ->fetchField();
-
-  // If there is a type_column, get bundle_id by specifying the data_table,
-  // type_column, and type_id.
-  $bundle_id = NULL;
-  if ($type_column) {
-    $schema = chado_get_schema($chado_table);
-    $pkey = is_array($schema['primary key']) ? $schema['primary key'][0] : $schema['primary key'];
-    $type_id = NULL;
-    if (key_exists($type_column, $schema['fields'])) {
-      $type_id =
-        db_select("chado.$chado_table", 'C')
-          ->fields('C', array($type_column))
-          ->condition($pkey, $record_id)
-          ->execute()
-          ->fetchField();
-    }
-    if ($type_id) {
-      $bundle_id =
-        db_select('chado_bundle', 'CB')
-          ->fields('CB', array('bundle_id'))
-          ->condition('data_table', $chado_table)
-          ->condition('type_column', $type_column)
-          ->condition('type_id', $type_id)
-          ->execute()
-          ->fetchField();
-    }
-  }
-  // If type_column is not used, get bundle_id by specifying the data_table.
-  else {
-    $bundle_id =
-      db_select('chado_bundle', 'CB')
-        ->fields('CB', array('bundle_id'))
-        ->condition('data_table', $chado_table)
-        ->execute()
-        ->fetchField();
-  }
-
-  // If bundle_id is found, find the bundle table name and return the entity_id.
-  $entity_id = NULL;
-  if ($bundle_id) {
-    $table_name =
-      db_select('tripal_bundle', 'TB')
-        ->fields('TB', array('name'))
-        ->condition('id', $bundle_id)
-        ->execute()
-        ->fetchField();
-    $entity_id =
-      db_select('chado_' . $table_name, 'CBD')
-        ->fields('CBD', array('entity_id'))
-        ->condition('record_id', $record_id)
-        ->execute()
-        ->fetchField();
-  }
-  return $entity_id;
-}

tripal_chado/api/tripal_chado.entity.api.inc

@@ -13,6 +13,7 @@
  * that use Chado as their base data.
  * @}
  */
+
 /**
  * Retreive the entity_id assigned to a given record_id and bundle.
  *
@@ -119,5 +120,4 @@ function chado_get_bundle_entity_table($bundle) {
     return '';
   }
   return 'chado_' . $bundle->name;
-}
-
+}

tripal_chado/api/tripal_chado.query.api.inc

@@ -6,148 +6,7 @@
  */
 
 /**
- * Get max rank for a given set of criteria
- * This function was developed with the many property tables in chado in mind but will
- * work for any table with a rank
- *
- * @params tablename: the name of the chado table you want to select the max rank from
- *    this table must contain a rank column of type integer
- * @params where_options: array(
- *   <column_name> => array(
- *     'type' => <type of column: INT/STRING>,
- *     'value' => <the value you want to filter on>,
- *     'exact' => <if TRUE use =; if FALSE use ~>,
- *    )
- *  )
- *  where options should include the id and type for that table to correctly
- *  group a set of records together where the only difference are the value and rank
- *
- * @return the maximum rank
- *
- * @ingroup tripal_chado_api
- */
-function chado_get_table_max_rank($tablename, $where_options) {
-
-  $where_clauses = array();
-  $where_args = array();
-
-  //generate the where clause from supplied options
-  // the key is the column name
-  $i = 0;
-  $sql = "
-    SELECT max(rank) as max_rank, count(rank) as count
-    FROM {".$tablename."}
-    WHERE
-  ";
-  foreach ($where_options as $key => $value) {
-    $where_clauses[] = "$key = :$key";
-    $where_args[":$key"] = $value;
-  }
-  $sql .= implode($where_clauses, ' AND ');
-
-  $result = chado_query($sql, $where_args)->fetchObject();
-  if ($result->count > 0) {
-    return $result->max_rank;
-  }
-  else {
-    return -1;
-  }
-
-}
-/**
- * Alter Chado connection settings.
- *
- * This hook is useful for multi-chado instances. Tripal core functions
- * call the chado_set_active() function (e.g. chado_query) but there is no
- * opportunity elsewhere to set the active database.  This is useful in two
- * cases:  1) Users are managed at the database level as in the case of
- * SouthGreen Bioinformatics Platform tools (e.g. Banana Genone Hub).
- * This allows custom modules to change the database connections on a per-user
- * basis, and each user permissions is managed at the database level.  Users
- * are managed at the database level to provid the same access restrictions
- * across various tools that use Chado (e,g, Artemis) 2) When there are
- * simply two Chado instances housed in different Chado databases and the
- * module needs to control which one is being used at any given time.
- *
- * @param $settings
- *   An array containing
- *
- * @see chado_set_active()
- *
- * @ingroup tripal_chado_api
- */
-function hook_chado_connection_alter(&$settings) {
-  // This example shows how we could make sure no table of the 'public' schema
-  // would be allowed in the coming queries: to do so, the caller will call
-  // "chado_set_active('chado_only');" and the hook will remove 'public' from
-  // the search path.
-  if ('chado_only' == $settings['dbname']) {
-    $settings['new_active_db']   = 'chado';
-    // We don't include 'public' in search path.
-    $settings['new_search_path'] = 'chado';
-  }
-}
-
-/**
- * Set the Tripal Database
- *
- * The chado_set_active function is used to prevent namespace collisions
- * when Chado and Drupal are installed in the same database but in different
- * schemas. It is also used when using Drupal functions such as
- * db_table_exists().
- *
- * The connection settings can be altered through the hook
- * hook_chado_connection_alter.
- *
- * Current active connection name is stored in the global variable
- * $GLOBALS['chado_active_db'].
- *
- * @see hook_chado_connection_alter()
- *
- * @ingroup tripal_chado_api
- */
-function chado_set_active($dbname = 'default') {
-
-  // Check if the chado_active_db has been set yet.
-  if (!array_key_exists('chado_active_db', $GLOBALS)) {
-    $GLOBALS['chado_active_db'] = 'default';
-  }
-
-  $previous_db = $active_db = $GLOBALS['chado_active_db'];
-  $search_path = tripal_get_schema_name('drupal');
-
-  // Change only if 'chado' has been specified.
-  // Notice that we leave the active_db set as chado but use the possibly user-altered
-  // schema name for the actual search path. This is to keep outward facing mentions of
-  // chado as "chado" while still allowing the user to alter the schema name used.
-  if ($dbname == 'chado') {
-    $active_db = 'chado';
-    $search_path = tripal_get_schema_name('chado') . ',' . tripal_get_schema_name('drupal');
-  }
-  else {
-    $active_db = $dbname;
-  }
-
-  $settings = array(
-    'dbname'          => $dbname,
-    'new_active_db'   => &$active_db,
-    'new_search_path' => &$search_path,
-  );
-
-  // Will call all modules implementing hook_chado_search_path_alter
-  // note: hooks can alter $active_db and $search_path.
-  drupal_alter('chado_connection', $settings);
-
-  // set chado_active_db to remember active db
-  $GLOBALS['chado_active_db'] = $active_db;
-
-  // set PostgreSQL search_path
-  db_query('SET search_path TO ' . $search_path);
-
-  return $previous_db;
-}
-/**
- * @defgroup tripal_chado_query_api Chado Query API
+ * @defgroup tripal_chado_query_api Chado Query
  * @ingroup tripal_chado_api
  * @{
  * Provides an API for querying of chado including inserting, updating, deleting and
@@ -318,10 +177,10 @@ function chado_set_active($dbname = 'default') {
  * chado_generate_var([table], [filter criteria], [optional options])
  * function. An example of how to use this function is:
  * @code
-   $values = array(
-     'name' => 'Medtr4g030710'
-   );
-   $features = chado_generate_var('feature', $values);
+ $values = array(
+ 'name' => 'Medtr4g030710'
+ );
+ $features = chado_generate_var('feature', $values);
  * @endcode
  * This will return an object if there is only one feature with the name Medtr4g030710 or it will
  * return an array of feature objects if more than one feature has that name.
@@ -331,20 +190,164 @@ function chado_set_active($dbname = 'default') {
  * chado_expand_var([chado variable], [type], [what to expand], [optional options])
  * function. An example of how to use this function is:
  * @code
-   // Get a chado object to be expanded
-   $values = array(
-     'name' => 'Medtr4g030710'
-   );
-   $features = chado_generate_var('feature', $values);
-   // Expand the organism node
-   $feature = chado_expand_var($feature, 'node', 'organism');
-   // Expand the feature.residues field
-   $feature = chado_expand_var($feature, 'field', 'feature.residues');
-   // Expand the feature properties (featureprop table)
-   $feature = chado_expand_var($feature, 'table', 'featureprop');
+ // Get a chado object to be expanded
+ $values = array(
+ 'name' => 'Medtr4g030710'
+ );
+ $features = chado_generate_var('feature', $values);
+ // Expand the organism node
+ $feature = chado_expand_var($feature, 'node', 'organism');
+ // Expand the feature.residues field
+ $feature = chado_expand_var($feature, 'field', 'feature.residues');
+ // Expand the feature properties (featureprop table)
+ $feature = chado_expand_var($feature, 'table', 'featureprop');
  * @endcode
  */
 
+
+/**
+ * Get max rank for a given set of criteria
+ * This function was developed with the many property tables in chado in mind but will
+ * work for any table with a rank
+ *
+ * @params tablename: the name of the chado table you want to select the max rank from
+ *    this table must contain a rank column of type integer
+ * @params where_options: array(
+ *   <column_name> => array(
+ *     'type' => <type of column: INT/STRING>,
+ *     'value' => <the value you want to filter on>,
+ *     'exact' => <if TRUE use =; if FALSE use ~>,
+ *    )
+ *  )
+ *  where options should include the id and type for that table to correctly
+ *  group a set of records together where the only difference are the value and rank
+ *
+ * @return the maximum rank
+ *
+ * @ingroup tripal_chado_query_api
+ */
+function chado_get_table_max_rank($tablename, $where_options) {
+
+  $where_clauses = array();
+  $where_args = array();
+
+  //generate the where clause from supplied options
+  // the key is the column name
+  $i = 0;
+  $sql = "
+    SELECT max(rank) as max_rank, count(rank) as count
+    FROM {".$tablename."}
+    WHERE
+  ";
+  foreach ($where_options as $key => $value) {
+    $where_clauses[] = "$key = :$key";
+    $where_args[":$key"] = $value;
+  }
+  $sql .= implode($where_clauses, ' AND ');
+
+  $result = chado_query($sql, $where_args)->fetchObject();
+  if ($result->count > 0) {
+    return $result->max_rank;
+  }
+  else {
+    return -1;
+  }
+
+}
+/**
+ * Alter Chado connection settings.
+ *
+ * This hook is useful for multi-chado instances. Tripal core functions
+ * call the chado_set_active() function (e.g. chado_query) but there is no
+ * opportunity elsewhere to set the active database.  This is useful in two
+ * cases:  1) Users are managed at the database level as in the case of
+ * SouthGreen Bioinformatics Platform tools (e.g. Banana Genone Hub).
+ * This allows custom modules to change the database connections on a per-user
+ * basis, and each user permissions is managed at the database level.  Users
+ * are managed at the database level to provid the same access restrictions
+ * across various tools that use Chado (e,g, Artemis) 2) When there are
+ * simply two Chado instances housed in different Chado databases and the
+ * module needs to control which one is being used at any given time.
+ *
+ * @param $settings
+ *   An array containing
+ *
+ * @see chado_set_active()
+ *
+ * @ingroup tripal_chado_query_api
+ */
+function hook_chado_connection_alter(&$settings) {
+  // This example shows how we could make sure no table of the 'public' schema
+  // would be allowed in the coming queries: to do so, the caller will call
+  // "chado_set_active('chado_only');" and the hook will remove 'public' from
+  // the search path.
+  if ('chado_only' == $settings['dbname']) {
+    $settings['new_active_db']   = 'chado';
+    // We don't include 'public' in search path.
+    $settings['new_search_path'] = 'chado';
+  }
+}
+
+/**
+ * Set the Tripal Database
+ *
+ * The chado_set_active function is used to prevent namespace collisions
+ * when Chado and Drupal are installed in the same database but in different
+ * schemas. It is also used when using Drupal functions such as
+ * db_table_exists().
+ *
+ * The connection settings can be altered through the hook
+ * hook_chado_connection_alter.
+ *
+ * Current active connection name is stored in the global variable
+ * $GLOBALS['chado_active_db'].
+ *
+ * @see hook_chado_connection_alter()
+ *
+ * @ingroup tripal_chado_query_api
+ */
+function chado_set_active($dbname = 'default') {
+
+  // Check if the chado_active_db has been set yet.
+  if (!array_key_exists('chado_active_db', $GLOBALS)) {
+    $GLOBALS['chado_active_db'] = 'default';
+  }
+
+  $previous_db = $active_db = $GLOBALS['chado_active_db'];
+  $search_path = tripal_get_schema_name('drupal');
+
+  // Change only if 'chado' has been specified.
+  // Notice that we leave the active_db set as chado but use the possibly user-altered
+  // schema name for the actual search path. This is to keep outward facing mentions of
+  // chado as "chado" while still allowing the user to alter the schema name used.
+  if ($dbname == 'chado') {
+    $active_db = 'chado';
+    $search_path = tripal_get_schema_name('chado') . ',' . tripal_get_schema_name('drupal');
+  }
+  else {
+    $active_db = $dbname;
+  }
+
+  $settings = array(
+    'dbname'          => $dbname,
+    'new_active_db'   => &$active_db,
+    'new_search_path' => &$search_path,
+  );
+
+  // Will call all modules implementing hook_chado_search_path_alter
+  // note: hooks can alter $active_db and $search_path.
+  drupal_alter('chado_connection', $settings);
+
+  // set chado_active_db to remember active db
+  $GLOBALS['chado_active_db'] = $active_db;
+
+  // set PostgreSQL search_path
+  db_query('SET search_path TO ' . $search_path);
+
+  return $previous_db;
+}
+
+
 /**
  * Provides a generic routine for inserting into any Chado table
  *
@@ -1713,6 +1716,8 @@ function chado_query($sql, $args = array()) {
  * @param $args
  *    An array of arguments where the key is the token used in $sql (for example, :value)
  *    and the value is the value you would like substituted in.
+ *
+ * @ingroup tripal_chado_query_api
  */
 function hook_chado_query_alter(&$sql, &$args) {
 
@@ -1856,7 +1861,6 @@ function chado_pager_get_count($element) {
  * species.  The cvterm is also specified using its foreign key and the cv_id
  * for the cvterm is nested as well.
  *
- * @ingroup tripal_chado
  */
 function chado_schema_get_foreign_key($table_desc, $field, $values, $options = NULL) {
 
@@ -1937,6 +1941,8 @@ function chado_schema_get_foreign_key($table_desc, $field, $values, $options = N
  *   Wehter you want the schema name for 'chado' or 'drupal'. Chado is the default.
  * @return
  *   The name of the PostgreSQL schema housing the $schema specified.
+ *
+ * @ingroup tripal_chado_query_api
  */
 function tripal_get_schema_name($schema = 'chado') {
 
@@ -1976,6 +1982,8 @@ function tripal_get_schema_name($schema = 'chado') {
  *     - schema: this is the schema that was passed to tripal_get_schema_name() and will
  *       be either "chado" or "drupal". This should be used to determine you are changing
  *       the name of the correct schema.
+ *
+ * @ingroup tripal_chado_query_api
  */
 function hook_tripal_get_schema_name_alter($schema_name, $context) {
 
@@ -2006,6 +2014,8 @@ function hook_tripal_get_schema_name_alter($schema_name, $context) {
  *
  * @return
  *   A new SelectQuery object for this connection.
+ *
+ * @ingroup tripal_chado_query_api
  */
 function chado_db_select($table, $alias = NULL, array $options = array()) {
   if (empty($options['target'])) {

tripal_chado/api/tripal_chado.schema.api.inc

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

tripal_chado/api/tripal_chado.schema_v1.11.api.inc

@@ -5,7 +5,7 @@
  */
 
 /**
- * @defgroup tripal_schema_v1_11_api Chado v1.11 Schema API
+ * @defgroup tripal_schema_v1_11_api Chado v1.11 Schema
  * @ingroup tripal_chado_schema_api
  * @{
  * Provides an application programming interface (API) for describing Chado tables.

tripal_chado/api/tripal_chado.schema_v1.2.api.inc

@@ -5,7 +5,7 @@
  */
 
 /**
- * @defgroup tripal_schema_v1_2_api Chado v1.2 Schema API
+ * @defgroup tripal_schema_v1_2_api Chado v1.2 Schema
  * @ingroup tripal_chado_schema_api
  * @{
  * Provides an application programming interface (API) for describing Chado tables.

tripal_chado/api/tripal_chado.schema_v1.3.api.inc

@@ -5,7 +5,7 @@
  */
 
 /**
- * @defgroup tripal_schema_v1_3_api Chado v1.3 Schema API
+ * @defgroup tripal_schema_v1_3_api Chado v1.3 Schema
  * @ingroup tripal_chado_schema_api
  * @{
  * Provides an application programming interface (API) for describing Chado

tripal_chado/includes/tripal_chado.pub_search.inc

@@ -133,7 +133,7 @@ function tripal_chado_pub_search_page() {
             }
           }
           // try tripal v3 link (entity), if it exists, update the link to entity
-          $entity_id = tripal_get_chado_entity_id ('pub', $pub->pub_id);
+          $entity_id = chado_get_record_entity_by_table('pub', $pub->pub_id);
           if ($entity_id) {
             $link = "/bio_data/$entity_id";
           }

tripal_chado/tripal_chado.module

@@ -14,7 +14,6 @@
  */
 /**
  * @defgroup tripal_chado_api Chado API
- * @ingroup tripal
  * @{
  * The Tripal Chado (tripal_chado) module provides an application programming
  * interface (API) to support customizations and creation of new extensions

tripal_ws/api/tripal_ws.api.inc

@@ -7,7 +7,7 @@
  */
 
 /**
- * @defgroup tripal_ws_api Tripal Web Services API
+ * @defgroup tripal_ws_api Web Services
  *
  * @ingroup tripal_api
  * The Tripal Web Services API provides a set of functions for interacting