Organism: cleaned up doc

tripal_organism/api/tripal_organism.api.inc

@@ -1,4 +1,8 @@
 <?php
+/**
+ * @file
+ * Provides an application programming interface (API) to manage organisms
+ */
 
 /**
  * @defgroup tripal_organism_api Organism API
@@ -9,22 +13,28 @@
  */
 
 /**
- * Purpose: Return a given organism object using the nid
+ * Return a given organism object using the nid
  *
- * @return organism object created by node load
+ * @param $nid
+ *  The node id (nid) of the organism node of interest
+ *
+ * @return
+ *  organism object created by node load
  *
  * @ingroup tripal_organism_api
  */
 function tripal_organism_get_organism_by_nid($nid) {
-
   return node_load($nid);
-
 }
 
 /**
- * Purpose: Return a given organism object using the organism id
+ * Return a given organism object using the organism id
  *
- * @return organism object created by node load
+ * @param $organism_id
+ *   The chado organism.organism_id of the organism of interest
+ *
+ * @return
+ *   organism object created by node load
  *
  * @ingroup tripal_organism_api
  */
@@ -44,7 +54,11 @@ function tripal_organism_get_organism_by_organism_id($organism_id) {
 }
 
 /**
- *  Returns a list of organisms that are currently synced with Drupal
+ * Returns a list of organisms that are currently synced with Drupal
+ *
+ * @return
+ *   An array of organisms sync'd with Drupal where each value is an organism table record
+ *
  * @ingroup tripal_organism_api
  */
 function tripal_organism_get_synced() {
@@ -65,13 +79,20 @@ function tripal_organism_get_synced() {
     $org = chado_query($csql, $args)->fetchObject();
     $org_list[] = $org;
   }
+
   return $org_list;
 }
 
 /**
+ * Return the URL for the organism image
  *
  * @param $organism
+ *   An organism table record
  * @param $nid
+ *   (Optional) the node id of the organism node. if not supplied it will be looked up
+ *
+ * @return
+ *   The fully qualified url to the image
  */
 function tripal_organism_get_image_url($organism, $nid = NULL) {
   $url = '';
@@ -94,4 +115,4 @@ function tripal_organism_get_image_url($organism, $nid = NULL) {
      }
   }
   return $url;
-}
+}

tripal_organism/includes/tripal_organism.admin.inc

@@ -1,7 +1,13 @@
 <?php
+/**
+ * @file
+ * Administration of organisms
+ */
 
 /**
+ * Admin launchpad
  *
+ * @ingroup tripal_organism
  */
 function tripal_organism_admin_organism_view() {
   $output = '';
@@ -51,6 +57,7 @@ function tripal_organism_admin() {
 
 
 /**
+ * Validate the organism settings form
  *
  * @ingroup tripal_organism
  */
@@ -93,8 +100,13 @@ function tripal_organism_admin_validate($form, &$form_state) {
   }
 }
 
-
 /**
+ * Add a job to reindex the features associated with an organism for drupal search
+ *
+ * @param $organism_id
+ *  The organism_id of the organism to re-index features of
+ * @param $job_id
+ *  (optional) specify a tripal job_id to create
  *
  * @ingroup tripal_organism
  */
@@ -129,7 +141,14 @@ function tripal_organism_reindex_features($organism_id = NULL, $job_id = NULL) {
     $i++;
   }
 }
+
 /**
+ * Add a tripal job to add drupal taxonomy to organisms
+ *
+ * @param $organism_id
+ *  The organism_id of the organism to add taxonomy to
+ * @param $job_id
+ *  (optional) specify a tripal job_id to create
  *
  * @ingroup tripal_organism
  */

tripal_organism/includes/tripal_organism.chado_node.inc

@@ -1,6 +1,13 @@
 <?php
 /**
- *  Provide information to drupal about the node types that we're creating
+ * @file
+ * Implements the organims node content type
+ */
+
+/**
+ *  Implements hook_node_info().
+ *
+ * Provide information to drupal about the node types that we're creating
  *  in this module
  *
  * @ingroup tripal_organism
@@ -30,8 +37,9 @@ function tripal_organism_node_info() {
   );
   return $nodes;
 }
+
 /**
- * Implement hook_access().
+ * Implement hook_node_access().
  *
  * This hook allows node modules to limit access to the node types they define.
  *
@@ -78,14 +86,124 @@ function chado_organism_node_access($node, $op, $account) {
   }
   return NULL;
 }
+
 /**
- * Implementation of hook_validate
+ *  Implement hook_form().
+ *
+ *  When editing or creating a new node of type 'chado_organism' we need
+ *  a form.  This function creates the form that will be used for this.
+ *
+ * @ingroup tripal_organism
+ */
+function chado_organism_form($node, $form_state) {
+  $form = array();
+
+  // we have a file upload element on the form soe we need the multipart encoding type
+  $form['#attributes']['enctype'] = 'multipart/form-data';
+
+  // if the organism is part of the node object then we are editing. If not we are inserting
+  if (property_exists($node, 'organism')) {
+    $organism = $node->organism;
+
+    // add in the comment since it is a text field and may not be included if too big
+    $organism = chado_expand_var($organism, 'field', 'organism.comment');
+
+    // get form defaults
+    $abbreviation   = property_exists($node, 'abbreviation')   ? property_exists($node, 'abbreviation')   : $organism->abbreviation;
+    $genus          = property_exists($node, 'genus')          ? property_exists($node, 'genus')          : $organism->genus;
+    $species        = property_exists($node, 'species')        ? property_exists($node, 'species')        : $organism->species;
+    $common_name    = property_exists($node, 'common_name')    ? property_exists($node, 'common_name')    : $organism->common_name;
+    $description    = property_exists($node, 'description')    ? property_exists($node, 'description')    : $organism->comment;
+    $organism_image = property_exists($node, 'organism_image') ? property_exists($node, 'organism_image') : '';
+
+    // set the organism_id in the form
+    $form['organism_id'] = array(
+      '#type' => 'value',
+      '#value' => $organism->organism_id,
+    );
+    $organism_id = $organism->organism_id;
+  }
+  else {
+    // get form defaults
+    $abbreviation   = property_exists($node, 'abbreviation')   ? property_exists($node, 'abbreviation')   : '';
+    $genus          = property_exists($node, 'genus')          ? property_exists($node, 'genus')          : '';
+    $species        = property_exists($node, 'species')        ? property_exists($node, 'species')        : '';
+    $common_name    = property_exists($node, 'common_name')    ? property_exists($node, 'common_name')    : '';
+    $description    = property_exists($node, 'description')    ? property_exists($node, 'description')    : '';
+    $organism_image = property_exists($node, 'organism_image') ? property_exists($node, 'organism_image') : '';
+
+    $organism_id = NULL;
+  }
+
+  $form['genus']= array(
+    '#type' => 'textfield',
+    '#title' => t('Genus'),
+    '#required' => TRUE,
+    '#default_value' => $genus,
+  );
+  $form['species']= array(
+    '#type' => 'textfield',
+    '#title' => t('Species'),
+    '#required' => TRUE,
+    '#default_value' => $species,
+  );
+  $form['abbreviation']= array(
+    '#type' => 'textfield',
+    '#title' => t('Abbreviation'),
+    '#required' => TRUE,
+    '#default_value' => $abbreviation,
+  );
+  $form['common_name']= array(
+    '#type' => 'textfield',
+    '#title' => t('Common Name'),
+    '#required' => TRUE,
+    '#default_value' => $common_name,
+  );
+  $form['description']= array(
+    '#type' => 'textarea',
+    '#rows' => 15,
+    '#title' => t('Description'),
+    '#default_value' => $description,
+  );
+  $form['organism_image']= array(
+    '#type' => 'file',
+    '#title' => t('Organism Image'),
+    '#description' => 'Add an image for this organism',
+    '#progress_indicator' => 'bar',
+  );
+
+  // PROPERTIES FORM
+  //---------------------------------------------
+  $details = array(
+    'property_table' => 'organismprop',      // the name of the prop table
+    'base_foreign_key' => 'organism_id',     // the name of the key in your base chado table
+    'base_key_value' => $organism_id,        // the value of organism_id for this record
+    'cv_name' => 'organism_property'         // the cv.name of the cv governing organismprop.type_id
+  );
+  // Adds the form elements to your current form
+  chado_add_node_form_properties($form, $form_state, $details);
+
+  // ADDITIONAL DBXREFS FORM
+  //---------------------------------------------
+  $details = array(
+    'linking_table' => 'organism_dbxref',  // the name of the _dbxref table
+    'base_foreign_key' => 'organism_id',   // the name of the key in your base chado table
+    'base_key_value' => $organism_id       // the value of organism_id for this record
+  );
+  // Adds the form elements to your current form
+  chado_add_node_form_dbxrefs($form, $form_state, $details);
+
+  return $form;
+}
+
+/**
+ * Implementation of hook_validate().
  *
  * @param $node
  * @param $form
  * @param $form_state
  *
- *  @ingroup tripal_organism
+ * @ingroup tripal_organism
  */
 function chado_organism_validate($node, $form, &$form_state) {
   // remove any white space around values
@@ -143,7 +261,10 @@ function chado_organism_validate($node, $form, &$form_state) {
     }
   }
 }
+
 /**
+ *  Implements hook_insert().
+ *
  *  When a new chado_organism node is created we also need to add information
  *  to our chado_organism table.  This function is called on insert of a new node
  *  of type 'chado_organism' and inserts the necessary information.
@@ -216,8 +337,9 @@ function chado_organism_insert($node) {
   // add the image
   chado_organism_add_image($node);
 }
+
 /**
- * Update organisms
+ * Implements hook_update().
  *
  * @ingroup tripal_organism
  */
@@ -267,7 +389,10 @@ function chado_organism_update($node) {
   );
   chado_update_node_form_dbxrefs($node, $details);
 }
+
 /**
+ * Implements hook_delete().
+ *
  * Delete organism from both drupal and chado databases. Check dependency before
  * deleting from chado.
  *
@@ -309,7 +434,12 @@ function chado_organism_delete($node) {
 }
 
 /**
+ * Add an image to an organims node
+ *
+ * @param $node
+ *   The node to add an image to
  *
+ * The file is specified in the $_FILES array created by Drupal
  *
  * @ingroup tripal_organism
  */
@@ -337,115 +467,9 @@ function chado_organism_add_image($node) {
   }
 }
 
-
 /**
- *  When editing or creating a new node of type 'chado_organism' we need
- *  a form.  This function creates the form that will be used for this.
+ *  Implements hook_load().
  *
- * @ingroup tripal_organism
- */
-function chado_organism_form($node, $form_state) {
-  $form = array();
-
-  // we have a file upload element on the form soe we need the multipart encoding type
-  $form['#attributes']['enctype'] = 'multipart/form-data';
-
-  // if the organism is part of the node object then we are editing. If not we are inserting
-  if (property_exists($node, 'organism')) {
-    $organism = $node->organism;
-
-    // add in the comment since it is a text field and may not be included if too big
-    $organism = chado_expand_var($organism, 'field', 'organism.comment');
-
-    // get form defaults
-    $abbreviation   = property_exists($node, 'abbreviation')   ? property_exists($node, 'abbreviation')   : $organism->abbreviation;
-    $genus          = property_exists($node, 'genus')          ? property_exists($node, 'genus')          : $organism->genus;
-    $species        = property_exists($node, 'species')        ? property_exists($node, 'species')        : $organism->species;
-    $common_name    = property_exists($node, 'common_name')    ? property_exists($node, 'common_name')    : $organism->common_name;
-    $description    = property_exists($node, 'description')    ? property_exists($node, 'description')    : $organism->comment;
-    $organism_image = property_exists($node, 'organism_image') ? property_exists($node, 'organism_image') : '';
-
-    // set the organism_id in the form
-    $form['organism_id'] = array(
-      '#type' => 'value',
-      '#value' => $organism->organism_id,
-    );
-    $organism_id = $organism->organism_id;
-  }
-  else {
-    // get form defaults
-    $abbreviation   = property_exists($node, 'abbreviation')   ? property_exists($node, 'abbreviation')   : '';
-    $genus          = property_exists($node, 'genus')          ? property_exists($node, 'genus')          : '';
-    $species        = property_exists($node, 'species')        ? property_exists($node, 'species')        : '';
-    $common_name    = property_exists($node, 'common_name')    ? property_exists($node, 'common_name')    : '';
-    $description    = property_exists($node, 'description')    ? property_exists($node, 'description')    : '';
-    $organism_image = property_exists($node, 'organism_image') ? property_exists($node, 'organism_image') : '';
-
-    $organism_id = NULL;
-  }
-
-  $form['genus']= array(
-    '#type' => 'textfield',
-    '#title' => t('Genus'),
-    '#required' => TRUE,
-    '#default_value' => $genus,
-  );
-  $form['species']= array(
-    '#type' => 'textfield',
-    '#title' => t('Species'),
-    '#required' => TRUE,
-    '#default_value' => $species,
-  );
-  $form['abbreviation']= array(
-    '#type' => 'textfield',
-    '#title' => t('Abbreviation'),
-    '#required' => TRUE,
-    '#default_value' => $abbreviation,
-  );
-  $form['common_name']= array(
-    '#type' => 'textfield',
-    '#title' => t('Common Name'),
-    '#required' => TRUE,
-    '#default_value' => $common_name,
-  );
-  $form['description']= array(
-    '#type' => 'textarea',
-    '#rows' => 15,
-    '#title' => t('Description'),
-    '#default_value' => $description,
-  );
-  $form['organism_image']= array(
-    '#type' => 'file',
-    '#title' => t('Organism Image'),
-    '#description' => 'Add an image for this organism',
-    '#progress_indicator' => 'bar',
-  );
-
-  // PROPERTIES FORM
-  //---------------------------------------------
-  $details = array(
-    'property_table' => 'organismprop',      // the name of the prop table
-    'base_foreign_key' => 'organism_id',     // the name of the key in your base chado table
-    'base_key_value' => $organism_id,        // the value of organism_id for this record
-    'cv_name' => 'organism_property'         // the cv.name of the cv governing organismprop.type_id
-  );
-  // Adds the form elements to your current form
-  chado_add_node_form_properties($form, $form_state, $details);
-
-  // ADDITIONAL DBXREFS FORM
-  //---------------------------------------------
-  $details = array(
-    'linking_table' => 'organism_dbxref',  // the name of the _dbxref table
-    'base_foreign_key' => 'organism_id',   // the name of the key in your base chado table
-    'base_key_value' => $organism_id       // the value of organism_id for this record
-  );
-  // Adds the form elements to your current form
-  chado_add_node_form_dbxrefs($form, $form_state, $details);
-
-  return $form;
-}
-
-/**
  *  When a node is requested by the user this function is called to allow us
  *  to add auxiliary data to the node object.
  *
@@ -469,11 +493,14 @@ function chado_organism_load($nodes) {
 }
 
 /**
+ * Implements hook_node_presave(). Acts on all content types.
  *
  * @param $node
+ *  The node to be saved
+ *
+ * @ingroup tripal_organism
  */
 function tripal_organism_node_presave($node) {
- print_r($node->organism);
   switch ($node->type) {
     case 'chado_organism':
       // for a form submission the 'genus' field will be set,
@@ -489,9 +516,11 @@ function tripal_organism_node_presave($node) {
       break;
   }
 }
+
 /**
+ * Implements hook_node_view().
  *
- * @ingroup tripal_feature
+ * @ingroup tripal_organism
  */
 function tripal_organism_node_view($node, $view_mode, $langcode) {
   switch ($node->type) {
@@ -522,4 +551,4 @@ function tripal_organism_node_view($node, $view_mode, $langcode) {
       }
       break;
   }
-}
+}

tripal_organism/tripal_organism.install

@@ -1,12 +1,14 @@
 <?php
-
 /**
  * @file
  * Functions pertaining to the install/uninstall of this module
  */
 
 /**
+ * Implements hook_disable().
  * Disable default views when module is disabled
+ *
+ * @ingroup tripal_organism
  */
 function tripal_organism_disable() {
 
@@ -87,6 +89,7 @@ function tripal_organism_uninstall() {
 /**
  * Implementation of hook_requirements().
  *
+ * @ingroup tripal_organism
  */
 function tripal_organism_requirements($phase) {
   $requirements = array();
@@ -104,15 +107,18 @@ function tripal_organism_requirements($phase) {
 }
 
 /**
+ * Add cvterms related to organisms
  *
+ * @ingroup tripal_organism
  */
 function tripal_organism_add_cvs() {
-
   tripal_cv_add_cv('organism_property', 'Contains properties for organisms');
-
 }
+
 /**
+ * Add cvterms pertaining to organisms
  *
+ * @ingroup tripal_organism
  */
 function tripal_organism_add_cvterms() {
 
@@ -120,6 +126,8 @@ function tripal_organism_add_cvterms() {
 
 /**
  * This is the required update for tripal_organism when upgrading from Drupal core API 6.x.
+ *
+ * @ingroup tripal_organism
  */
 function tripal_organism_update_7000() {
 

tripal_organism/tripal_organism.module

@@ -1,8 +1,13 @@
 <?php
+/**
+ * @file
+ * Integrates the Chado Organism module with Drupal Nodes & Views
+ */
+
+require_once 'api/tripal_organism.api.inc';
 
-require_once "api/tripal_organism.api.inc";
-require_once "includes/tripal_organism.admin.inc";
-require_once "includes/tripal_organism.chado_node.inc";
+require_once 'includes/tripal_organism.admin.inc';
+require_once 'includes/tripal_organism.chado_node.inc';
 
 /**
  * @defgroup tripal_organism Organism Module
@@ -13,16 +18,7 @@ require_once "includes/tripal_organism.chado_node.inc";
  */
 
 /**
- *
- * @ingroup tripal_organism
- */
-function tripal_organism_init() {
-
-}
-
-
-
-/**
+ * Implements hook_block_info().
  *
  * @ingroup tripal_organism
  */
@@ -34,7 +30,9 @@ function tripal_organism_block_info() {
   return $blocks;
 
 }
+
 /**
+ * Implements hook_block_view().
  *
  * @ingroup tripal_organism
  */
@@ -55,8 +53,11 @@ function tripal_organism_block_view($delta = '') {
     return $block;
   }
 }
+
 /**
- *  Menu items are automatically added for the new node types created
+ *  Implements hook_menu().
+ *
+ * Menu items are automatically added for the new node types created
  *  by this module to the 'Create Content' Navigation menu item.  This function
  *  adds more menu items needed for this module.
  *
@@ -117,8 +118,10 @@ function tripal_organism_menu() {
 }
 
 /**
- * Implements hook_help()
- * Purpose: Adds a help page to the module list
+ * Implements hook_help().
+ * Adds a help page to the module list
+ *
+ * @ingroup tripal_organism
  */
 function tripal_organism_help ($path, $arg) {
   if ($path == 'admin/help#tripal_organism') {
@@ -127,6 +130,8 @@ function tripal_organism_help ($path, $arg) {
 }
 
 /**
+ *  Implements hook_theme().
+ *
  *  We need to let drupal know about our theme functions and their arguments.
  *  We create theme functions to allow users of the module to customize the
  *  look and feel of the output generated in this module
@@ -205,9 +210,11 @@ function tripal_organism_permission() {
     ),
   );
 }
+
 /**
- * Implements hook_views_api()
- * Purpose: Essentially this hook tells drupal that there is views support for
+ * Implements hook_views_api().
+ *
+ * Essentially this hook tells drupal that there is views support for
  *  for this module which then includes tripal_db.views.inc where all the
  *  views integration code is
  *
@@ -215,11 +222,12 @@ function tripal_organism_permission() {
  */
 function tripal_organism_views_api() {
   return array(
-    'api' => 2.0,
+    'api' => 3.0,
   );
 }
+
 /**
- *
+ * Implements hook_job_describe_args().
  *
  * @ingroup tripal_organism
  */
@@ -235,15 +243,17 @@ function tripal_organism_job_describe_args($callback, $args) {
 
 
 /**
- * Implementation of hook_form_alter()
+ * Implementation of hook_form_alter().
  *
  * @param $form
  * @param $form_state
  * @param $form_id
+ *
+ * @ingroup tripal_organism
  */
 function tripal_organism_form_alter(&$form, &$form_state, $form_id) {
   // turn of preview button for insert/updates
   if ($form_id == "chado_organism_node_form") {
     $form['actions']['preview']['#access'] = FALSE;
   }
-}
+}

tripal_organism/tripal_organism.views_default.inc

@@ -1,8 +1,13 @@
 <?php
+/**
+ * @file
+ * Organism default views
+ */
 
 /**
+ * Implements hook_views_default_views().
  *
- *
+ * @ingroup tripal_organism
  */
 function tripal_organism_views_default_views() {
   $views = array();
@@ -13,6 +18,11 @@ function tripal_organism_views_default_views() {
   return $views;
 }
 
+/**
+ * Describe the organism administration view.
+ *
+ * @ingroup tripal_organism
+ */
 function tripal_organism_admin_defaultview_organisms() {
 
   $view = new view();
@@ -206,4 +216,4 @@ function tripal_organism_admin_defaultview_organisms() {
   */
 
   return $view;
-}
+}