Analysis: cleaned up documentation

tripal_analysis/api/tripal_analysis.api.inc

@@ -1,10 +1,16 @@
 <?php
+/**
+ * @file
+ * Provides functions for managing analysis'.
+ *
+ * @ingroup tripal_analysis
+ */
 
 /**
  * @defgroup tripal_analysis_api Analysis Module API
  * @ingroup tripal_api
  * @{
- * API functions relating to Analysis'
+ * Provides an interface for specialized analysis modules to extend the basic functionality.
  * @}
  */
 
@@ -38,6 +44,7 @@ function tripal_analysis_api_unregister_child($modulename) {
       db_query($sql, array(':modname' => $modulename));
   }
 }
+
 /**
  * Retrieve properties of a given type for a given analysis
  *
@@ -51,7 +58,7 @@ function tripal_analysis_api_unregister_child($modulename) {
  * @return
  *    An analysis chado variable with the specified properties expanded
  *
- * @ingroup tripal_analysis_api_api
+ * @ingroup tripal_analysis_api
  */
 function tripal_analysis_api_get_property($analysis_id, $property, $cvname = 'tripal') {
   return tripal_core_get_property('analysis', $analysis_id, $property, $cvname);
@@ -74,7 +81,7 @@ function tripal_analysis_api_get_property($analysis_id, $property, $cvname = 'tr
  * @return
  *   True of success, False otherwise
  *
- * @ingroup tripal_analysis_api_api
+ * @ingroup tripal_analysis_api
  */
 function tripal_analysis_api_insert_property($analysis_id, $property, $value, $update_if_present = 0, $cvname = 'tripal') {
     return tripal_core_insert_property('analysis', $analysis_id, $property, $cvname, $value, $update_if_present);
@@ -100,7 +107,7 @@ function tripal_analysis_api_insert_property($analysis_id, $property, $value, $u
  * @return
  *   True of success, False otherwise
  *
- * @ingroup tripal_analysis_api_api
+ * @ingroup tripal_analysis_api
  */
 function tripal_analysis_api_update_property($analysis_id, $property, $value, $insert_if_missing = 0, $cvname = 'tripal') {
   return tripal_core_update_property('analysis', $analysis_id, $property, $cvname, $value, $insert_if_missing);
@@ -122,7 +129,7 @@ function tripal_analysis_api_update_property($analysis_id, $property, $value, $i
  * @return
  *   True of success, False otherwise
  *
- * @ingroup tripal_analysis_api_api
+ * @ingroup tripal_analysis_api
  */
 function tripal_analysis_api_delete_property($analysis_id, $property, $cvname = 'tripal') {
   return tripal_core_delete_property('analysis', $analysis_id, $property, $cvname);
@@ -137,7 +144,7 @@ function tripal_analysis_api_delete_property($analysis_id, $property, $cvname =
  * @return
  *   node of analysis on success, null otherwise
  *
- * @ingroup tripal_analysis_api_api
+ * @ingroup tripal_analysis_api
  */
 function tripal_analysis_api_get_node($analysis_id) {
   $sql = "SELECT *

tripal_analysis/includes/tripal_analysis.admin.inc

@@ -2,11 +2,15 @@
 
 /**
  * @file
- * Contains functions displaying administrative pages and forms
+ * Contains functions displaying administrative pages and forms.
+ *
+ * @ingroup tripal_analysis
  */
 
 /**
+ * Landing page for administration. Ensures Views are enabled & if not provides links to do so.
  *
+ * @ingroup tripal_analysis
  */
 function tripal_analysis_admin_analysis_view() {
   $output = '';
@@ -94,10 +98,6 @@ function tripal_analysis_admin() {
   return system_settings_form($form);
 }
 
-
-
-
-
 /**
  * Validate the administrative form
  * @todo Stephen: Why is validate used rather then submit?
@@ -149,3 +149,4 @@ function tripal_analysis_admin_validate($form, &$form_state) {
     }
   }
 }
+

tripal_analysis/includes/tripal_analysis.chado_node.inc

@@ -1,5 +1,13 @@
 <?php
 /**
+ * @file
+ * Implements Drupal Node hooks to create the chado_analysis node content type.
+ *
+ * @ingroup tripal_analysis
+ */
+
+/**
+ * Implements hook_node_info().
  * Provide information to drupal about the node types that we're creating
  * in this module
  *
@@ -30,9 +38,11 @@ function tripal_analysis_node_info() {
   );
   return $nodes;
 }
+
 /**
- *  When editing or creating a new node of type 'chado_analysis' we need
- *  a form.  This function creates the form that will be used for this.
+ * Implements hook_form().
+ * When editing or creating a new node of type 'chado_analysis' we need
+ * a form.  This function creates the form that will be used for this.
  *
  * @ingroup tripal_analysis
  */
@@ -235,7 +245,9 @@ function chado_analysis_form($node, &$form_state) {
 
   return $form;
 }
+
 /**
+ * Implements hook_validate().
  * Validates the user input before creating an analysis node
  *
  * @ingroup tripal_analysis
@@ -346,9 +358,10 @@ function tripal_analysis_validate($node, $form, &$form_state) {
 }
 
 /**
- *  When a new chado_analysis node is created we also need to add information
- *  to our chado_analysis table.  This function is called on insert of a new
- *  node of type 'chado_analysis' and inserts the necessary information.
+ * Implements hook_insert().
+ * When a new chado_analysis node is created we also need to add information
+ * to our chado_analysis table.  This function is called on insert of a new
+ * node of type 'chado_analysis' and inserts the necessary information.
  *
  * @ingroup tripal_analysis
  */
@@ -427,10 +440,8 @@ function chado_analysis_insert($node) {
 }
 
 /**
- * Removes analysis from the chado database
- *
- * @param $node
- *   The node object specifying which chado record to delete
+ * Implements hook_delete().
+ * Removes analysis from the chado database.
  *
  * @ingroup tripal_analysis
  */
@@ -456,11 +467,9 @@ function chado_analysis_delete($node) {
 }
 
 /**
+ * Implements hook_update().
  * Update analyses
  *
- * @param $node
- *   The updated node object
- *
  * @ingroup tripal_analysis
  */
 function chado_analysis_update($node) {
@@ -514,9 +523,11 @@ function chado_analysis_update($node) {
   );
   chado_node_properties_form_update_properties($node, $details);
 }
+
 /**
- *  When a node is requested by the user this function is called to allow us
- *  to add auxiliary data to the node object.
+ * Implements hook_load().
+ * When a node is requested by the user this function is called to allow us
+ * to add auxiliary data to the node object.
  *
  * @ingroup tripal_analysis
  */
@@ -537,7 +548,7 @@ function chado_analysis_load($nodes) {
 }
 
 /**
- * Implement hook_access().
+ * Implements hook_access().
  *
  * This hook allows node modules to limit access to the node types they define.
  *
@@ -584,7 +595,10 @@ function chado_analysis_node_access($node, $op, $account) {
   }
   return NULL;
 }
+
 /**
+ * Implements hook_node_view().
+ * Called for all node types.
  *
  * @ingroup tripal_analysis
  */
@@ -613,21 +627,24 @@ function tripal_analysis_node_view($node, $view_mode, $langcode) {
       break;
   }
 }
+
 /**
+ * Implements hook_node_presave().
+ * Called for all node types.
  *
- * @param $node
+ * @ingroup tripal_analysis
  */
 function tripal_analysis_node_presave($node) {
   $name = '';
   $program = '';
   $programversion = '';
   $sourcename = '';
-  
+
   // If this is an analysis of some type it will should have three required
   // fields for the Chado analysis table: program, programversion and sourcename.
   // So we will set the title for any node that has these three fields. Some extension
   // modules will use this module as a type of "inherited" class, so we don't know
-  // for sure when type of analysis we have.  If this is a sync then 
+  // for sure when type of analysis we have.  If this is a sync then
   if (property_exists($node, 'program') and
       property_exists($node, 'programversion') and
       property_exists($node, 'sourcename')) {
@@ -652,4 +669,4 @@ function tripal_analysis_node_presave($node) {
       $node->title = $name;
     }
   }
-}
+}

tripal_analysis/includes/tripal_analysis_privacy.inc

@@ -1,7 +1,9 @@
 <?php
 /**
  * @file
- * Perform permission check (required node_privacy_byrole module)
+ * Perform permission check (required node_privacy_byrole module).
+ *
+ * @ingroup tripal_analysis
  */
 
 /**
@@ -9,6 +11,8 @@
  *
  * @param $analysis_id
  *   Which analysis to check if the user has permission to view
+ *
+ * @ingroup tripal_analysis
  */
 function tripal_analysis_check_permission($analysis_id) {
   if (module_exists('node_privacy_byrole')) {
@@ -17,9 +21,9 @@ function tripal_analysis_check_permission($analysis_id) {
     $node_access = 0;
     foreach ($roles AS $rid => $role) {
       $p_sql = "
-        SELECT grant_view 
-        FROM {node_access} NA 
-          INNER JOIN {chado_analysis} CA ON NA.nid = CA.nid 
+        SELECT grant_view
+        FROM {node_access} NA
+          INNER JOIN {chado_analysis} CA ON NA.nid = CA.nid
         WHERE analysis_id = :analysis_id AND gid = :gid";
       $access = db_query($p_sql, array(':analysis_id' => $analysis_id, ':gid' => $rid))->fetchField();
       if ($access == 1) {
@@ -49,6 +53,8 @@ function tripal_analysis_check_permission($analysis_id) {
  *   Features associated with this analysis will have their permissions set
  * @param $nid
  *   The node ID of the analysis
+ *
+ * @ingroup tripal_analysis
  */
 function tripal_analysis_set_feature_permission($analysis_id, $nid) {
 
@@ -89,10 +95,10 @@ function tripal_analysis_set_feature_permission($analysis_id, $nid) {
       $rsql = "SELECT * FROM {node_privacy_byrole} WHERE gid = :gid AND nid = :nid AND realm = 'node_privacy_byrole_role'";
       $ana_perm = db_query($rsql, array(':gid' => $rid, ':nid' => $ana_nid))->fetchObject();
       db_query("INSERT INTO {node_privacy_byrole} (nid, gid, realm, grant_view, grant_update, grant_delete)
-                VALUES (:nid, :gid, :realm, :grant_view, :grant_update, :grant_delete)", 
-                array(':nid' => $fnid, ':gid' => $rid, ':realm' => 'node_privacy_byrole_role', 
-                      ':grant_view' => $ana_perm->grant_view, 
-                      ':grant_update' => $ana_perm->grant_update, 
+                VALUES (:nid, :gid, :realm, :grant_view, :grant_update, :grant_delete)",
+                array(':nid' => $fnid, ':gid' => $rid, ':realm' => 'node_privacy_byrole_role',
+                      ':grant_view' => $ana_perm->grant_view,
+                      ':grant_update' => $ana_perm->grant_update,
                       ':grant_delete' => $ana_perm->grant_delete));
     }
     $node = node_load($fnid);

tripal_analysis/tripal_analysis.install

@@ -1,11 +1,16 @@
 <?php
 /**
  * @file
- * Implements hooks from the Schema API
+ * Implements hooks from the Schema API.
+ *
+ * @ingroup tripal_analysis
  */
 
 /**
+ * Implements hook_disable().
  * Disable default views when module is disabled
+ *
+ * @ingroup tripal_analysis
  */
 function tripal_analysis_disable() {
 
@@ -20,6 +25,8 @@ function tripal_analysis_disable() {
 
 /**
  * Implementation of hook_requirements().
+ *
+ * @ingroup tripal_analysis
  */
 function tripal_analysis_requirements($phase) {
   $requirements = array();
@@ -38,6 +45,8 @@ function tripal_analysis_requirements($phase) {
 
 /**
  * Implementation of hook_install().
+ *
+ * @ingroup tripal_analysis
  */
 function tripal_analysis_install() {
 
@@ -56,12 +65,18 @@ function tripal_analysis_install() {
 
 /**
  * Implementation of hook_uninstall().
+ *
+ * @ingroup tripal_analysis
  */
 function tripal_analysis_uninstall() {
 
 }
+
 /**
- * 
+ * Create a legacy custom chado table (analysisfeatureprop) to store properties of
+ * analysisfeature links.
+ *
+ * @ingroup tripal_analysis
  */
 function tripal_analysis_create_analysisfeatureprop() {
 
@@ -83,8 +98,11 @@ function tripal_analysis_create_analysisfeatureprop() {
     chado_query($sql);
   }
 }
-/*
+
+/**
+ * Adds controlled vocabulary terms needed by this module.
  *
+ * @ingroup tripal_analysis
  */
 function tripal_analysis_add_cvterms() {
 
@@ -113,13 +131,15 @@ function tripal_analysis_add_cvterms() {
 }
 
 /**
- * Implementation of hook_schema() creates two tables.
+ * Implementation of hook_schema().
  *
  * - chado_analysis table
  *     stores nodes that are also saved in the analysis table of chado database.
  * - tripal_analysis table
  *     stores the sub-module names, such as tripal_analysis_blast, that are registered
  *     with this module.
+ *
+ * @ingroup tripal_analysis
  */
 function tripal_analysis_schema() {
 
@@ -173,9 +193,10 @@ function tripal_analysis_schema() {
   return $schema;
 }
 
-/*
+/**
+ * Creates a view showing hte link between an organism & it's analysis through associated features.
  *
- * @ingroup tripal_network
+ * @ingroup tripal_analysis
  */
 function tripal_analysis_add_mview_analysis_organism() {
   $view_name = 'analysis_organism';
@@ -229,3 +250,4 @@ function tripal_analysis_add_mview_analysis_organism() {
   // add the view
   tripal_add_mview($view_name, 'tripal_analysis', $schema, $sql, $comment);
 }
+

tripal_analysis/tripal_analysis.module

@@ -1,21 +1,29 @@
 <?php
 
 /**
- * @defgroup tripal_analysis Analysis Module
- * @ingroup tripal_modules
- * @{
- * Provides functions for managing chado analysis' including creating details pages for each one
- * @}
+ * @file
+ * Contains basic functionality for the analysis module.
+ *
+ * @ingroup tripal_analysis
  */
 
 require_once 'api/tripal_analysis.api.inc';
+require_once 'api/tripal_analysis.schema.api.inc';
+
 require_once 'includes/tripal_analysis_privacy.inc';
 require_once 'includes/tripal_analysis.admin.inc';
 require_once 'includes/tripal_analysis.chado_node.inc';
-require_once "api/tripal_analysis.schema.api.inc";
 
+/**
+ * @defgroup tripal_analysis Analysis Module
+ * @ingroup tripal_modules
+ * @{
+ * Integrates the Chado Analysis module with Drupal Nodes & Views
+ * @}
+ */
 
 /**
+ * Implements hook_init().
  * Add tripal javascript to page headers
  *
  * @ingroup tripal_analysis
@@ -77,8 +85,10 @@ function tripal_analysis_menu() {
 }
 
 /**
- * Implements hook_help()
+ * Implements hook_help().
  * Purpose: Adds a help page to the module list
+ *
+ * @ingroup tripal_analysis
  */
 function tripal_analysis_help ($path, $arg) {
   if ($path == 'admin/help#tripal_analysis') {
@@ -87,6 +97,7 @@ function tripal_analysis_help ($path, $arg) {
 }
 
 /**
+ *  Implements hook_permission().
  *  Set the permission types that the chado module uses.  Essentially we
  *  want permissionis that protect creation, editing and deleting of chado
  *  data objects
@@ -168,7 +179,7 @@ function tripal_analysis_theme($existing, $type, $theme, $path) {
   return $items;
 }
 /**
- *
+ * Implements hook_block_info().
  *
  * @ingroup tripal_analysis
  */
@@ -183,7 +194,7 @@ function tripal_analysis_block_info() {
 }
 
 /**
- *
+ * Implements hook_block_view().
  *
  * @ingroup tripal_analysis
  */
@@ -212,8 +223,8 @@ function tripal_analysis_block_view($delta = '') {
 
 
 /**
- * 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_analysis.views.inc where all the
  *  views integration code is
  *
@@ -221,16 +232,14 @@ function tripal_analysis_block_view($delta = '') {
  */
 function tripal_analysis_views_api() {
   return array(
-    'api' => 2.0,
+    'api' => 3.0,
   );
 }
 
 /**
- * Implementation of hook_form_alter()
+ * Implementation of hook_form_alter().
  *
- * @param $form
- * @param $form_state
- * @param $form_id
+ * @ingroup tripal_analysis
  */
 function tripal_analysis_form_alter(&$form, &$form_state, $form_id) {
   // turn of preview button for insert/updates

tripal_analysis/tripal_analysis.views_default.inc

@@ -1,7 +1,16 @@
 <?php
 
+/**
+ * @file
+ * Contains the default views for the analysis module.
+ *
+ * @ingroup tripal_analysis
+ */
+
 /**
  * Implements hook_views_default_views().
+ *
+ * @ingroup tripal_analysis
  */
 function tripal_analysis_views_default_views() {
   $views = array();
@@ -12,6 +21,11 @@ function tripal_analysis_views_default_views() {
   return $views;
 }
 
+/**
+ * Defines the analysis admin default view.
+ *
+ * @ingroup tripal_analysis
+ */
 function tripal_analysis_defaultvalue_admin_analysis() {
 
   $view = new view();
@@ -190,4 +204,4 @@ function tripal_analysis_defaultvalue_admin_analysis() {
   $handler->display->display_options['tab_options']['weight'] = '0';
 
   return $view;
-}
+}