Merge branch '7.x-2.x' of git.drupal.org:sandbox/spficklin/1337878 into 7.x-2.x

tripal_pub/api/tripal_pub.api.inc

@@ -68,12 +68,18 @@ function tripal_pub_get_remote_search_results($remote_db, $search_array, $num_to
 }
 
 /**
- * @stephen
+ * This function is used to perfom a query using one of the supported databases
+ * and return the raw query results. This may be XML or some other format 
+ * as provided by the database.
  *
  * @param $dbxref
- *
+ *   The unique database ID for the record to retrieve.  This value must
+ *   be of the format DB_NAME:ACCESSION where DB_NAME is the name of the 
+ *   database (e.g. PMID or AGL) and the ACCESSION is the unique identifier
+ *   for the record in the database.
+ *   
  * @return
- *
+ *   Returns the raw output wrapped in an HTML textarea element
  *
  * @ingroup tripal_pub_api
  */
@@ -109,12 +115,23 @@ function tripal_pub_get_raw_data($dbxref) {
 }
 
 /**
- * @stephen
+ * Updates publication records with the most recent data in the remote
+ * database.
  *
  * @param $do_contact
+ *   Set to TRUE if authors should automatically have a contact record added
+ *   to Chado. Contacts are added using the name provided by the remote
+ *   database.
  * @param $dbxref
+ *   The unique database ID for the record to update.  This value must
+ *   be of the format DB_NAME:ACCESSION where DB_NAME is the name of the 
+ *   database (e.g. PMID or AGL) and the ACCESSION is the unique identifier
+ *   for the record in the database.
  * @param $db
- *
+ *   The name of the remote database to update.  If this value is provided and 
+ *   no dbxref then all of the publications currently in the Chado database
+ *   for this remote database will be updated.
+ *   
  * @ingroup tripal_pub_api
  */
 function tripal_pub_update_publications($do_contact = FALSE, $dbxref = NULL, $db = NULL) {
@@ -203,10 +220,12 @@ function tripal_pub_update_publications($do_contact = FALSE, $dbxref = NULL, $db
 }
 
 /**
- * @stephen
+ * Imports all publications for a given publication import setup. 
  *
  * @param $import_id
+ *   The ID of the import setup to use
  * @param $job_id
+ *   The jobs management job_id for the job if this function is run as a job.
  *
  * @ingroup tripal_pub_api
  */
@@ -270,11 +289,15 @@ function tripal_pub_import_publications_by_import_id($import_id, $job_id = NULL)
 }
 
 /**
- * @stephen
+ * Imports all publications for all active import setups.
  *
  * @param $report_email
+ *   A list of email address, separated by commas, that should be notified
+ *   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
+ *   
  * @ingroup tripal_pub_api
  */
 function tripal_pub_import_publications($report_email = FALSE, $do_update = FALSE) {
@@ -364,12 +387,20 @@ function tripal_pub_import_publications($report_email = FALSE, $do_update = FALS
 }
 
 /**
- * @stephen
+ * Imports a singe publication specified by a remote database cross reference.
  *
  * @param $pub_dbxref
+ *   The unique database ID for the record to update.  This value must
+ *   be of the format DB_NAME:ACCESSION where DB_NAME is the name of the 
+ *   database (e.g. PMID or AGL) and the ACCESSION is the unique identifier
+ *   for the record in the database.
  * @param $do_contact
+ *   Set to TRUE if authors should automatically have a contact record added
+ *   to Chado. 
  * @param $do_update
- *
+ *   If set to TRUE then the publication will be updated if it already exists
+ *   in the database.
+ *   
  * @ingroup tripal_pub_api
  */
 function tripal_pub_import_by_dbxref($pub_dbxref, $do_contact = FALSE, $do_update) {
@@ -430,13 +461,22 @@ function tripal_pub_import_by_dbxref($pub_dbxref, $do_contact = FALSE, $do_updat
 }
 
 /**
- * @stephen
+ * Adds publications that have been retrieved from a remote database and 
+ * consolidated into an array of details.
  *
  * @param $pubs
+ *   An array containing a list of publications to add to Chado.  The
+ *   array contains a set of details for the publication.
  * @param $do_contact
+ *   Set to TRUE if authors should automatically have a contact record added
+ *   to Chado. 
  * @param $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
+ *   
  * @return
+ *   Returns an array containing the number of publications that were
+ *   inserted, updated, skipped and which had an error during import.
  *
  * @ingroup tripal_pub_api
  */
@@ -485,12 +525,14 @@ function tripal_pub_add_publications($pubs, $do_contact, $update = FALSE) {
 }
 
 /**
- * Adds a dbxref record to a publication
- *
- * @stephen
+ * Adds a database cross-reference to a publication
  *
  * @param $pub_id
+ *   The ID of the publication   
  * @param $pub_dbxref
+ *   The cross reference.  This value must be of the format DB_NAME:ACCESSION 
+ *   where DB_NAME is the name of the database and the 
+ *   ACCESSION is the unique identifier for the record in the database.
  *
  * @return
  *
@@ -515,8 +557,8 @@ function tripal_pub_add_pub_dbxref($pub_id, $pub_dbxref) {
       'accession' => $accession,
       'db_id' => array(
         'name' => $dbname,
-  ),
-  ),
+      ),
+    ),
     'pub_id' => $pub_id,
   );
   $options = array('statement_name' => 'sel_pubdbxref_dbpu');
@@ -909,12 +951,16 @@ function tripal_pub_add_publication($pub_details, &$action, $do_contact = FALSE,
 }
 
 /**
- * @stephen
+ * Add one or more authors to a publication
  *
  * @param $pub_id
+ *   The publication ID of the pub in Chado.
  * @param $authors
+ *   An array of authors.  Each author should have a set of keys/value pairs
+ *   describing the author.
  * @param $do_contact
- *
+ *   Optional. Set to TRUE if a contact entry should be added to the Chado contact table
+ *   for authors of the publication.
  * @ingroup tripal_pub_api
  */
 function tripal_pub_add_authors($pub_id, $authors, $do_contact) {

tripal_pub/includes/importers/tripal_pub.AGL.inc

@@ -1,15 +1,24 @@
 <?php
 /**
  * @file
- * @stephen
+ * This file provides support for importing and parsing of results from the 
+ * USDA National Agricultural Library (AGL) database.  The functions here are used by
+ * both the publication importer setup form and the publication importer.
+ * 
+ * The USDA AGL database uses a YAZ protocol for querying and retrieving records.
+ * 
  */
 
 /**
- * @stephen
+ * A hook for altering the publication importer form.  It Changes the 
+ * 'Days' element to 'Year' and removes the 'Journal Name' filter.
  *
  * @param $form
+ *   The Drupal form array
  * @param $form_state
+ *   The form state array
  * @param $num_criteria
+ *   The number of criteria the user currently has added to the form
  *
  * @return
  *   The form (drupal form api)
@@ -32,11 +41,13 @@ function tripal_pub_remote_alter_form_AGL($form, $form_state, $num_criteria = 1)
 }
 
 /**
- * @stephen
+ * A hook for providing additional validation of importer setup form.
  *
  * @param $form
+ *   The Drupal form array
  * @param $form_state
- *
+ *   The form state array
+ *  
  * @return
  *  The form (drupal form api)
  *
@@ -68,14 +79,19 @@ function tripal_pub_remote_validate_form_AGL($form, $form_state) {
 }
 
 /**
- * @stephen
+ * A hook for performing the search on the AGL database.
  *
  * @param $search_array
+ *   An array containing the serach criteria for the serach
  * @param $num_to_retrieve
+ *   Indicates the maximum number of publications to retrieve from the remote
+ *   database
  * @param $page
+ *   Indicates the page to retrieve.  This corresponds to a paged table, where
+ *   each page has $num_to_retrieve publications.
  *
  * @return
- *
+ *  An array of publications.
  *
  * @ingroup tripal_pub
  */
@@ -387,16 +403,23 @@ function tripal_pub_remote_search_AGL($search_array, $num_to_retrieve, $page) {
 }
 
 /**
- * @stephen
+ * Retreives a range of publications from AGL
  *
  * @param $yazc
+ *   The YAZC connection object.
  * @param $search_str
+ *   The search string to use for searching.
  * @param $start
+ *   The start of the range
  * @param $num_to_retrieve
+ *   The number of publications to retrieve
  * @param $total_records
- *
+ *   The total number of records in the dataset.  This value should have 
+ *   been retrieved by tripal_pub_AGL_count() function.
+ *   
  * @return
- *
+ *  An array containing the total_records in the dataaset, the search string
+ *  and an array of the publications that were retreived.
  *
  * @ingroup tripal_pub
  */
@@ -436,16 +459,15 @@ function tripal_pub_AGL_range($yazc, $search_str, $start, $num_to_retrieve, $tot
 }
 
 /**
- * This function is used as the callback function when used with the
- * tripal_pager_callback function.
- *
- * @stephen
+ * Retreives the total number of publications that match the search string.
  *
  * @param $yazc
+ *   The YAZC connection object.
  * @param $search_str
- *
+ *   The search string to use for searching.
+ *   
  * @return
- * a count of the dataset to be paged.
+ *   a count of the total number of publications that match the search string
  *
  * @ingroup tripal_pub
  */
@@ -883,12 +905,12 @@ function tripal_pub_AGL_parse_pubxml($pub_xml) {
 }
 
 /**
- * @stephen
+ * Used for parsing of the XML results to get a set of subfields 
  *
  * @param $xml
- *
+ *   The XMl object to read
  * @return
- *
+ *   An array of codes and their values
  *
  * @ingroup tripal_pub
  */
@@ -912,11 +934,14 @@ function tripal_pub_remote_search_AGL_get_subfield($xml) {
 }
 
 /**
- * @stephen
+ * Used for parsing of the XML results to get details about an author 
  *
  * @param $xml
+ *   The XML object to read
  * @param $ind1
- *
+ *   Indicates how an author record is stored; 0 means given name is first
+ *   1 means surname is first, 3 means a family name is given
+ *   
  * @return
  *
  *

tripal_pub/includes/importers/tripal_pub.PMID.inc

@@ -1,15 +1,26 @@
 <?php
 /**
  * @file
- * Tripal Pub PubMed Interface
+ * This file provides support for importing and parsing of results from the 
+ * NCBI PubMed database.  The functions here are used by
+ * both the publication importer setup form and the publication importer.
+ * 
  */
 
+
 /**
- * @stephen
+ * A hook for altering the publication importer form.  It Changes the 
+ * 'Abstract' filter to be 'Abstract/Title'.
  *
  * @param $form
+ *   The Drupal form array
  * @param $form_state
+ *   The form state array
  * @param $num_criteria
+ *   The number of criteria the user currently has added to the form
+ *
+ * @return
+ *   The form (drupal form api)
  *
  * @ingroup tripal_pub
  */
@@ -24,13 +35,15 @@ function tripal_pub_remote_alter_form_PMID($form, $form_state, $num_criteria = 1
 }
 
 /**
- * Validate the pub med form
+ * A hook for providing additional validation of importer setup form.
  *
  * @param $form
+ *   The Drupal form array
  * @param $form_state
- *
+ *   The form state array
+ *  
  * @return
- *   The form (drupal form api)
+ *  The form (drupal form api)
  *
  * @ingroup tripal_pub
  */
@@ -48,11 +61,19 @@ function tripal_pub_remote_validate_form_PMID($form, $form_state) {
 }
 
 /**
- * @stephen
+ * A hook for performing the search on the PubMed database.
  *
  * @param $search_array
+ *   An array containing the serach criteria for the serach
  * @param $num_to_retrieve
+ *   Indicates the maximum number of publications to retrieve from the remote
+ *   database
  * @param $page
+ *   Indicates the page to retrieve.  This corresponds to a paged table, where
+ *   each page has $num_to_retrieve publications.
+ *
+ * @return
+ *  An array of publications.
  *
  * @ingroup tripal_pub
  */
@@ -166,10 +187,16 @@ function tripal_pub_remote_search_PMID($search_array, $num_to_retrieve, $page) {
 }
 
 /**
- * @stephen
+ * Initailizes a PubMed Search using a given search string
  *
  * @param $search_str
+ *   The PubMed Search string
  * @param $retmax
+ *   The maximum number of records to return
+ *   
+ * @return 
+ *   An array containing the Count, WebEnv and QueryKey as return
+ *   by PubMed's esearch utility
  *
  * @ingroup tripal_pub
  */
@@ -235,20 +262,32 @@ function tripal_pub_PMID_search_init($search_str, $retmax){
 }
 
 /**
- * @stephen
+ * Retreives from PubMed a set of publications from the
+ * previously initiated query.
  *
  * @param $query_key
+ *   The esearch QueryKey
  * @param $web_env
+ *   The esearch WebEnv
  * @param $rettype
+ *   The efetch return type 
  * @param $retmod
+ *   The efetch return mode
  * @param $start
+ *   The start of the range to retrieve
  * @param $limit
+ *   The number of publications to retrieve
  * @param $args
+ *   Any additional arguments to add the efetch query URL
+ *   
+ * @return
+ *  An array containing the total_records in the dataaset, the search string
+ *  and an array of the publications that were retreived.
  *
  * @ingroup tripal_pub
  */
 function tripal_pub_PMID_fetch($query_key, $web_env, $rettype = 'null',
-$retmod = 'null', $start = 0, $limit = 10, $args = array()){
+  $retmod = 'null', $start = 0, $limit = 10, $args = array()){
 
   // repeat the search performed previously (using WebEnv & QueryKey) to retrieve
   // the PMID's within the range specied.  The PMIDs will be returned as a text list
@@ -292,7 +331,7 @@ $retmod = 'null', $start = 0, $limit = 10, $args = array()){
   return $results;
 }
 
-/*
+/**
  * This function parses the XML containing details of a publication and
  * converts it into an associative array of where keys are Tripal Pub
  * ontology terms and the values are extracted from the XML. The
@@ -405,10 +444,13 @@ function tripal_pub_PMID_parse_pubxml($pub_xml) {
 }
 
 /**
- * @stephen
+ * Parses the section from the XML returned from PubMed that contains
+ * information about the Journal 
  *
  * @param $xml
+ *   The XML to parse
  * @param $pub
+ *   The publication object to which additional details will be added
  *
  * @ingroup tripal_pub
  */
@@ -445,10 +487,13 @@ function tripal_pub_PMID_parse_medline_journal_info($xml, &$pub) {
 }
 
 /**
- * @stephen
+ * Parses the section from the XML returned from PubMed that contains
+ * information about an article.
  *
  * @param $xml
+ *   The XML to parse
  * @param $pub
+ *   The publication object to which additional details will be added
  *
  * @ingroup tripal_pub
  */
@@ -537,7 +582,8 @@ function tripal_pub_PMID_parse_article($xml, &$pub) {
 }
 
 /**
- * @stephen
+ * Parses the section from the XML returned from PubMed that contains
+ * information about a publication
  *
  * A full list of publication types can be found here:
  * http://www.nlm.nih.gov/mesh/pubtypes.html.
@@ -546,7 +592,9 @@ function tripal_pub_PMID_parse_article($xml, &$pub) {
  * publication types so we store the value in the 'publication_type' term.
  *
  * @param $xml
+ *   The XML to parse
  * @param $pub
+ *   The publication object to which additional details will be added
  *
  * @ingroup tripal_pub
  */
@@ -585,10 +633,13 @@ function tripal_pub_PMID_parse_publication_type($xml, &$pub) {
 }
 
 /**
- * @stephen
+ * Parses the section from the XML returned from PubMed that contains
+ * information about the abstract
  *
  * @param $xml
+ *   The XML to parse
  * @param $pub
+ *   The publication object to which additional details will be added
  *
  * @ingroup tripal_pub
  */
@@ -632,10 +683,13 @@ function tripal_pub_PMID_parse_abstract($xml, &$pub) {
 }
 
 /**
- * @stephen
+ * Parses the section from the XML returned from PubMed that contains
+ * information about pagination
  *
  * @param $xml
+ *   The XML to parse
  * @param $pub
+ *   The publication object to which additional details will be added
  *
  * @ingroup tripal_pub
  */
@@ -663,10 +717,13 @@ function tripal_pub_PMID_parse_pagination($xml, &$pub) {
 }
 
 /**
- * @stephen
+ * Parses the section from the XML returned from PubMed that contains
+ * information about a journal
  *
  * @param $xml
+ *   The XML to parse
  * @param $pub
+ *   The publication object to which additional details will be added
  *
  * @ingroup tripal_pub
  */
@@ -713,10 +770,13 @@ function tripal_pub_PMID_parse_journal($xml, &$pub) {
 }
 
 /**
- * @stephen
+ * Parses the section from the XML returned from PubMed that contains
+ * information about a journal issue
  *
  * @param $xml
+ *   The XML to parse
  * @param $pub
+ *   The publication object to which additional details will be added
  *
  * @ingroup tripal_pub
  */
@@ -771,10 +831,13 @@ function tripal_pub_PMID_parse_journal_issue($xml, &$pub) {
 }
 
 /**
- * @stephen
+ * Parses the section from the XML returned from PubMed that contains
+ * information regarding to dates
  *
  * @param $xml
- * @param $element_name
+ *   The XML to parse
+ * @param $pub
+ *   The publication object to which additional details will be added
  *
  * @ingroup tripal_pub
  */
@@ -817,10 +880,13 @@ function tripal_pub_PMID_parse_date($xml, $element_name) {
 }
 
 /**
- * @stephen
+ * Parses the section from the XML returned from PubMed that contains
+ * information about the author list for a publication
  *
  * @param $xml
+ *   The XML to parse
  * @param $pub
+ *   The publication object to which additional details will be added
  *
  * @ingroup tripal_pub
  */

tripal_pub/includes/tripal_pub.pub_importers.inc

@@ -70,10 +70,16 @@ function tripal_pub_importers_list() {
 }
 
 /**
- * @stephen
+ * Creates the page that contains the publication importer setup form and 
+ * test results.
  *
  * @param $action
+ *   The action to perform
  * @param $pub_import_id
+ *   The importer ID
+ *   
+ * @return
+ *   The HTML for the importer setup page
  *
  * @ingroup tripal_pub
  */
@@ -200,14 +206,19 @@ function tripal_pub_importer_setup_page($action = 'new', $pub_import_id = NULL)
 }
 
 /**
- * Provides the form to search pubmed
- *
- * @stephen
+ * The form used for creating publication importers.
  *
  * @param $form
+ *   The Drupal form
  * @param $form_state
+ *   The form state
  * @param $pub_import_id
+ *   The publication importer ID
  * @param $action
+ *   The action to perform
+ *   
+ * @return
+ *   A form array
  *
  * @ingroup tripal_pub
  */
@@ -400,12 +411,20 @@ function tripal_pub_importer_setup_form($form, &$form_state = NULL, $pub_import_
 }
 
 /**
- * @stephen
+ * A helper function for the importer setup form that adds the criteria to 
+ * the form that belong to the importer.
  *
  * @param $form
+ *   The form
  * @param $form_state
+ *   The form state
  * @param $num_criteria
+ *   The number of criteria that exist for the importer
  * @param $criteria
+ *   An array containing the criteria
+ *
+ *@return
+ *  A form array
  *
  * @ingroup tripal_pub
  */

tripal_pub/includes/tripal_pub.pub_search.inc

@@ -1,11 +1,14 @@
 <?php
 /**
  * @file
- * Functions related to searching remote publication databases
+ * 
+ * Functions responsible for creating the publication search form that 
+ * allows a user of the site to search for publications that are currently 
+ * in Chado.
  */
 
 /**
- * @stephen
+ * The page that contains the publication search form and the results for the search
  *
  * @ingroup tripal_pub
  */
@@ -448,35 +451,14 @@ function tripal_pub_search_form_submit($form, &$form_state) {
     unset($_SESSION['tripal_pub_search_form']);
   }
 }
-
 /**
- * AHAH callback
+ * Builds the SQL statement need to search Chado for the publications
+ * that match the user supplied criteria
  *
- * @ingroup tripal_pub
- */
-function tripal_pub_search_page_update_criteria($action, $i) {
-  $status = TRUE;
-
-  // prepare and render the form
-  $form = tripal_core_ahah_prepare_form();
-  $data = theme('tripal_pub_search_form', $form);
-
-  // bind javascript events to the new objects that will be returned
-  // so that AHAH enabled elements will work.
-  $settings = tripal_core_ahah_bind_events();
-
-  // return the updated JSON
-  drupal_json(
-  array(
-      'status'   => $status,
-      'data'     => $data,
-      'settings' => $settings,
-  )
-  );
-}
-
-/**
- * @stephen
+ * @param $search_array
+ *   An array of search criteria provided by the user
+ * @param $limit
+ *   The numbe of records to retrieve
  *
  * @ingroup tripal_pub
  */
@@ -591,6 +573,11 @@ function tripal_pub_get_search_results($search_array, $limit) {
 
 /**
  * Ajax callback to update the form
+ * 
+ * @param $form
+ *   The form array
+ * @param $form_state
+ *   The form state array
  *
  * @ingroup tripal_pub
  */