Bulk Loader: Documenation clean-up

tripal_bulk_loader/api/tripal_bulk_loader.api.templates.inc

@@ -1,4 +1,11 @@
 <?php
+/**
+ * @file
+ * Provides functions for hooking into bulk loader functionality.
+ *
+ * @ingroup tripal_bulk_loader
+ */
+
 /**
  * @defgroup tripal_bulk_loader_api Tripal Bulk Loader Module API
  * @ingroup tripal_api

tripal_bulk_loader/includes/tripal_bulk_loader.admin.inc

@@ -3,8 +3,15 @@
 /**
  * @file
  * Bulk Loader Administration (Miscellaneous)
+ *
+ * @ingroup tripal_bulk_loader
  */
 
+/**
+ * Landing page for bulk loader admin. Ensures views are enabled and if not provides links to do so.
+ *
+ * @ingroup tripal_bulk_loader
+ */
 function tripal_bulk_loader_admin_jobs_listing() {
   $output = '';
 

tripal_bulk_loader/includes/tripal_bulk_loader.admin.templates.inc

@@ -3,6 +3,8 @@
 /**
  * @file
  * All functions in this file pertain to administrative management of bulk loader templates
+ *
+ * @ingroup tripal_bulk_loader
  */
 
 /**
@@ -1389,6 +1391,8 @@ function tripal_bulk_loader_duplicate_template_record_form_submit($form, &$form_
 
 /**
  * Determine default values needed for add/edit field form
+ *
+ * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_template_field_form_default_values($mode, &$form_state) {
   $v = array();

tripal_bulk_loader/includes/tripal_bulk_loader.chado_node.inc

@@ -2,11 +2,13 @@
 
 /**
  * @file
- * Tripal Bulk Loader Node functionality (jobs)
+ * Tripal Bulk Loader Node functionality (jobs).
+ *
+ * @ingroup tripal_bulk_loader
  */
 
 /**
- * Implements hook_node_info
+ * Implements hook_node_info().
  *
  * @ingroup tripal_bulk_loader
  */
@@ -24,7 +26,7 @@ function tripal_bulk_loader_node_info() {
 }
 
 /**
- * Implements node_form
+ * Implements hook_form().
  * Used to gather the extra details stored with a Bulk Loading Job Node
  *
  * @ingroup tripal_bulk_loader
@@ -111,9 +113,10 @@ function tripal_bulk_loader_form($node, $form_state) {
 
 
 /**
- * Implements node_load
+ * Implements hook_load().
  *
  * D7 Changes: now loads all $nodes at once so need to add loops
+ *
  * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_load($nodes) {
@@ -212,7 +215,9 @@ function tripal_bulk_loader_load($nodes) {
 }
 
 /**
- * Implements hook_node_presave()
+ * Implements hook_node_presave().
+ * Acts on all node types.
+ *
  * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_node_presave($node) {
@@ -228,10 +233,11 @@ function tripal_bulk_loader_node_presave($node) {
 
 
 /**
- * Implements node_insert
+ * Implements hook_insert().
  * Insert the data from the node form on Create content
  *
  * D7 Changes: seems to need db_insert; not recommended to change $node
+ *
  * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_insert($node) {
@@ -250,7 +256,7 @@ function tripal_bulk_loader_insert($node) {
 }
 
 /**
- * Implements node_delete
+ * Implements hook_delete().
  * Deletes the data when the delete button on the node form is clicked
  *
  * @ingroup tripal_bulk_loader
@@ -268,10 +274,9 @@ function tripal_bulk_loader_delete($node) {
 }
 
 /**
- * Implements node_update
+ * Implements hook_update().
  * Updates the data submitted by the node form on edit
  *
- * D7 Changes: db_update is much easier
  * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_update($node) {
@@ -354,4 +359,4 @@ function tripal_bulk_loader_node_access($node, $op, $account) {
     return NODE_ACCESS_ALLOW;
   }
   return NODE_ACCESS_IGNORE;
-}
+}

tripal_bulk_loader/includes/tripal_bulk_loader.constants.inc

@@ -1,7 +1,9 @@
 <?php
 /**
  * @file
- * @todo Add file header description
+ * Manages the constants form added to the tripal bulk loader node form
+ *
+ * @ingroup tripal_bulk_loader
  */
 
 /**

tripal_bulk_loader/includes/tripal_bulk_loader.loader.inc

@@ -2,7 +2,9 @@
 
 /**
  * @file
- * @todo Add file header description
+ * Handles the actual loading of data.
+ *
+ * @ingroup tripal_bulk_loader
  */
 
 /**
@@ -1161,6 +1163,11 @@ function tripal_bulk_loader_progress_file_track_job($job_id, $record_added, $lin
   }
 }
 
+/**
+ * Used to throw a hopefully human-readable error.
+ *
+ * @ingroup tripal_bulk_loader
+ */
 function tripal_bulk_loader_throw_error($msg, $args, $severity) {
   $options = array('print' => TRUE);
   if ($severity == TRIPAL_NOTICE OR $severity == TRIPAL_INFO OR $severity == TRIPAL_DEBUG) {
@@ -1176,6 +1183,11 @@ function tripal_bulk_loader_throw_error($msg, $args, $severity) {
   );
 }
 
+/**
+ * Finishes the loading job by setting variables and exiting.
+ *
+ * @ingroup tripal_bulk_loader
+ */
 function tripal_bulk_loader_finish_loading($nid, $loaded_without_errors) {
 
   // set the status of the job (in the node not the tripal jobs)
@@ -1194,4 +1206,4 @@ function tripal_bulk_loader_finish_loading($nid, $loaded_without_errors) {
     drush_set_error('BULK_LOAD_FAILED', 'Execution aborted due to errors.');
     exit();
   }
-}
+}

tripal_bulk_loader/tripal_bulk_loader.drush.inc

@@ -1,12 +1,16 @@
 <?php
 
 /**
- *  @file
- *  Implements drush integration for this module
+ * @file
+ * Implements drush integration for this module
+ *
+ * @ingroup tripal_bulk_loader
  */
 
 /**
  * Implements hook_drush_command().
+ *
+ * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_drush_command() {
   $items = array();
@@ -65,6 +69,8 @@ function tripal_bulk_loader_drush_command() {
 /**
  * Code ran for the tripal-loader-progress drush command
  * Display the progress of any running tripal bulk loading job.
+ *
+ * @ingroup tripal_bulk_loader
  */
 function drush_tripal_bulk_loader_tripal_loader_progress() {
 
@@ -97,6 +103,8 @@ function drush_tripal_bulk_loader_tripal_loader_progress() {
  *
  * @param $nid
  *   The Node ID of the bulk Loading Job
+ *
+ * @ingroup tripal_bulk_loader
  */
 function drush_tripal_bulk_loader_tripal_loader_view ($nid) {
   $node = node_load($nid);
@@ -116,6 +124,8 @@ function drush_tripal_bulk_loader_tripal_loader_view ($nid) {
  *
  * @param $nid
  *   The Node ID of the bulk Loading Job
+ *
+ * @ingroup tripal_bulk_loader
  */
 function drush_tripal_bulk_loader_tripal_loader_cancel ($nid) {
   $node = node_load($nid);
@@ -128,6 +138,8 @@ function drush_tripal_bulk_loader_tripal_loader_cancel ($nid) {
  *
  * @param $nid
  *   The Node ID of the bulk Loading Job
+ *
+ * @ingroup tripal_bulk_loader
  */
 function drush_tripal_bulk_loader_tripal_loader_submit ($nid) {
   global $user;
@@ -164,6 +176,8 @@ function drush_tripal_bulk_loader_tripal_loader_submit ($nid) {
  *
  * @param $nid
  *   The Node ID of the bulk Loading Job
+ *
+ * @ingroup tripal_bulk_loader
  */
 function drush_tripal_bulk_loader_tripal_loader_revert ($nid) {
 
@@ -185,4 +199,4 @@ function drush_tripal_bulk_loader_tripal_loader_revert ($nid) {
   // reset status
   db_query("UPDATE {tripal_bulk_loader} SET job_status='%s' WHERE nid=%d", 'Reverted -Data Deleted', $nid);
 
-}
+}

tripal_bulk_loader/tripal_bulk_loader.install

@@ -1,11 +1,16 @@
 <?php
 /**
  * @file
- * @todo Add file header description
+ * Install/Uninstalls, Enables/Disables this module.
+ *
+ * @ingroup tripal_bulk_loader
  */
 
 /**
+ * Implements hook_disable().
  * Disable default views when module is disabled
+ *
+ * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_disable() {
 
@@ -19,12 +24,14 @@ function tripal_bulk_loader_disable() {
 }
 
 /**
- * Implements hook_schema
+ * Implements hook_schema().
  *
  * Creates the following tables in the Drupal database:
  *  - tripal_bulk_loader: Stores extra details for bulk loading jobs (nodes)
  *  - tripal_bulk_loader_template: Stores all loading templates
  *  - tripal_bulk_loader_inserted: Keeps track of all records inserted for a given bulk loading job
+ *
+ * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_schema() {
   $schema = array();
@@ -170,8 +177,12 @@ function tripal_bulk_loader_schema() {
 }
 
 /**
+ * Implements hook_update_N().
+ *
  * Update schema for version 6.x-0.3.1b-1.5
  * - Add the tripal_bulk_loader_constants table
+ *
+ * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_update_6150() {
 
@@ -184,9 +195,13 @@ function tripal_bulk_loader_update_6150() {
 }
 
 /**
+ * Implements hook_update_N().
+ *
  * Update schema for version 6.x-0.3.1b-1.5
  * - Add the tripal_bulk_loader_constants.group_id column
  *   to allow multiple sets of constants per job
+ *
+ * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_update_6151() {
 
@@ -205,6 +220,11 @@ function tripal_bulk_loader_update_6151() {
   return 'Added support for multiple sets of loader-specific constants.';
 }
 
+/**
+ * Implements hook_update_N().
+ *
+ * @ingroup tripal_bulk_loader
+ */
 function tripal_bulk_loader_update_6152() {
 
   db_add_field(
@@ -222,8 +242,12 @@ function tripal_bulk_loader_update_6152() {
 }
 
 /**
+ * Implements hook_update_N().
+ *
  * Update to 7.x-2.0
  * -Cast tripal_bulk_loader.template_id to int field
+ *
+ * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_update_7201() {
 
@@ -265,6 +289,8 @@ function tripal_bulk_loader_update_7201() {
 
 /**
  * Implementation of hook_requirements().
+ *
+ * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_requirements($phase) {
   $requirements = array();
@@ -279,4 +305,4 @@ function tripal_bulk_loader_requirements($phase) {
     }
   }
   return $requirements;
-}
+}

tripal_bulk_loader/tripal_bulk_loader.module

@@ -1,4 +1,10 @@
 <?php
+/**
+ * @file
+ * Provides general functions for the tripal bulk loader.
+ *
+ * @ingroup tripal_bulk_loader
+ */
 
 /**
  * @defgroup tripal_bulk_loader Tripal Bulk Loader Module
@@ -23,7 +29,7 @@ include('includes/tripal_bulk_loader.admin.templates.inc');
 include('api/tripal_bulk_loader.api.templates.inc');
 
 /**
- * Implements hook_init
+ * Implements hook_init().
  * Used to add stylesheets and javascript files to the header
  *
  * @ingroup tripal_bulk_loader
@@ -35,7 +41,7 @@ function tripal_bulk_loader_init() {
 }
 
 /**
- * Implements hook_menu
+ * Implements hook_menu().
  *
  * @ingroup tripal_bulk_loader
  */
@@ -226,16 +232,29 @@ function tripal_bulk_loader_menu() {
   return $items;
 }
 
+/**
+ * Implements hook_to_arg().
+ * Ensures the arguement for the bulk loader templates path is correct
+ *
+ * @ingroup tripal_bulk_loader
+ */
 function tblid_to_arg($arg, $map, $index) {
   if (preg_match('/^(\d+|O)$/', $arg)) {
     return $arg;
   }
 }
 
+/**
+ * Implements hook_load() for the menu system.
+ *
+ * Ensures that a number is passed to the form. We use the letter o in our path instead
+ * of the number 0 because the drupal menu system has a bug that doesn't allow 0 as
+ * the only character in the path.
+ *
+ * @ingroup tripal_bulk_loader
+ */
 function tblid_load($tblid_id) {
-  // We use the letter o in our path instead of the number 0
-  // because the drupal menu system has a bug that doesn't allow 0 as the only
-  // character in the path.
+
   if (preg_match('/O/',$tblid_id)) {
     // This ensures that the number 0 is sent to the form as the correct arg
     return 0;
@@ -246,13 +265,13 @@ function tblid_load($tblid_id) {
 }
 
 /**
- * Implements hook_views_api()
+ * Implements hook_views_api().
  *
- * Purpose: Essentially this hook tells drupal that there is views support for
- *  for this module which then includes tripal_views.views.inc where all the
- *  views integration code is
+ * Essentially this hook tells drupal that there is views support for
+ * for this module which then includes tripal_views.views.inc where all the
+ * views integration code is.
  *
- * @ingroup tripal_views
+ * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_views_api() {
   return array(
@@ -261,7 +280,7 @@ function tripal_bulk_loader_views_api() {
 }
 
 /**
- * Implements hook_theme
+ * Implements hook_theme().
  *
  * @ingroup tripal_bulk_loader
  */
@@ -296,7 +315,7 @@ function tripal_bulk_loader_theme() {
 }
 
 /**
- * Implements hook_perm
+ * Implements hook_permission().
  *
  * @ingroup tripal_bulk_loader
  */

tripal_bulk_loader/tripal_bulk_loader.views.inc

@@ -1,4 +1,10 @@
 <?php
+/**
+ * @file
+ * Provides Drupal views integration excluding default views.
+ *
+ * @ingroup tripal_bulk_loader
+ */
 
 /**
  * Generates a dynamic data array for Views
@@ -11,6 +17,8 @@
  * @return a data array formatted for the Views module
  *
  * D7 @todo: Add support for materialized views relationships using the new method
+ *
+ * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_views_data() {
   $data = array();
@@ -377,4 +385,4 @@ function tripal_bulk_loader_views_data() {
   );
 
   return $data;
-}
+}

tripal_bulk_loader/tripal_bulk_loader.views_default.inc

@@ -1,6 +1,15 @@
 <?php
+/**
+ * @file
+ * Defines the tripal bulk loader default views.
+ *
+ * @ingroup tripal_bulk_loader
+ */
+
 /**
  * Implements hook_views_default_views().
+ *
+ * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_views_default_views() {
   $views = array();
@@ -17,7 +26,9 @@ function tripal_bulk_loader_views_default_views() {
 }
 
 /**
- * Default Admin Vire for job management
+ * Default Admin View for job management
+ *
+ * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_defaultview_admin_job_listing() {
 
@@ -269,6 +280,8 @@ function tripal_bulk_loader_defaultview_admin_job_listing() {
 
 /**
  * Default Admin View for template management
+ *
+ * @ingroup tripal_bulk_loader
  */
 function tripal_bulk_loader_defaultview_admin_template_listing() {
 
@@ -421,4 +434,4 @@ function tripal_bulk_loader_defaultview_admin_template_listing() {
   $handler->display->display_options['menu']['context_only_inline'] = 0;
 
   return $view;
-}
+}